Request operation cancellation

Requests cancellation of an in-flight operation. Cancellation is asynchronous: successful requests return the current operation envelope while the worker drains the current step before settling into a terminal result. Replaying the request with the same Idempotency-Key is supported. If the operation has already reached a terminal state, cancellation is rejected with Unprocessable Entity.

When accepted, the operation is not cancelled instantly; it transitions through the normal cancellation flow and may still report progress for a short time.

POST /operations/{id}:cancel

Request operation cancellation

cURL

curl --request POST \
  --url https://api.akua.dev/v1/operations/{id}:cancel \
  --header 'Authorization: Bearer <token>'

202

{
  "id": "<string>",
  "workspace_id": "<string>",
  "organization_id": "<string>",
  "owner_id": "<string>",
  "parent_operation_id": "<string>",
  "done": true,
  "html_url": "https://app.akua.dev/dashboard/installs/inst_j572abc...?tab=operations",
  "metadata": {
    "cluster_id": "<string>"
  },
  "response": {
    "cluster_id": "<string>"
  },
  "error": {
    "message": "<string>"
  },
  "last_error": {
    "message": "<string>",
    "step_name": "<string>"
  },
  "started_at": 1,
  "completed_at": 1,
  "steps": [
    {
      "name": "<string>",
      "started_at": 1,
      "completed_at": 1,
      "error_message": "<string>",
      "retryable": true,
      "skippable": true
    }
  ]
}

Authorizations

Authorization · string · header · required

workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens

Headers

akua-context · string

Optional workspace/scope context for the request. Carries a single workspace wire id (ws_…) today. Only needed for broad tokens — a workspace-owned token implies its workspace.

Required string length: 1 - 53

Example:

"ws_j572abc123def456"

idempotency-key · string

Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.

Required string length: 1 - 64

Example:

"create-prod-2026-05-07"

if-match · string

Optional optimistic concurrency token for clients that track the latest operation revision.

Required string length: 1 - 64

Example:

"WzQ1Njc="

Path Parameters

id · string · required

Operation ID. Prefixed form op_<id> is canonical; bare IDs accepted during transition.

Required string length: 1 - 53

Example:

"op_j572abc..."

Response

202

application/json

Cancellation requested; operation transition is in progress

id · string · required

Required string length: 1 - 53

workspace_id · string | null · required

Required string length: 1 - 53

organization_id · string | null · required

Required string length: 1 - 54

owner_type · enum<string> · required

Domain entity collection the operation acts on.

Available options: install, repository_change_request, repository, workspace, machine, cluster, package

owner_id · string · required

Prefixed ID of the entity this operation acts on. Prefix matches owner_type (ws_, mch_, clu_, pkg_, inst_, rcr_, repo_).

parent_operation_id · string | null · required

ID of the chained parent operation, when present.

Required string length: 1 - 53

state · enum<string> · required

Lifecycle state. Past-participle terminal states per AIP-216.

Available options: RUNNING, SUCCEEDED, FAILED, CANCELLED

done · boolean · required

True iff state is a terminal value.

html_url · string<uri> · required

Deep link to the dashboard view of this operation.

Example:

"https://app.akua.dev/dashboard/installs/inst_j572abc...?tab=operations"

metadata · object · required

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Option 10

Option 11

Option 12

Option 13

Option 14

Option 15

Option 16

Option 17

Option 18

Option 19

Option 20

Option 21

Option 22

Option 23

Option 24

Option 25

Option 26

Option 27

Show child attributes

response · object · required

Populated only when done && state === "SUCCEEDED". Discriminated by type.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Option 10

Option 11

Option 12

Option 13

Option 14

Option 15

Option 16

Option 17

Option 18

Option 19

Option 20

Option 21

Option 22

Option 23

Option 24

Option 25

Option 26

Option 27

Show child attributes

error · object · required

Populated when state is FAILED or CANCELLED.

Show child attributes

last_error · object · required

Latest error from any failed step. Populated even mid-flight; cleared when the step succeeds on retry.

Show child attributes

started_at · integer · required

Unix timestamp (seconds)

Required range: x >= 0

completed_at · integer | null · required

Unix timestamp (seconds)

Required range: x >= 0

steps · object[]

Show child attributes