Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Request cancellation of a long-running operation
Requests cooperative cancellation of an in-flight operation. Cancellation is itself asynchronous: the server marks intent immediately and the worker stops at the next safe checkpoint, after which the operation reaches the CANCELLED terminal state. Side effects already applied before the checkpoint are rolled back where the action supports it; otherwise the target resource is left in its last consistent state and the operation's error field explains what was kept. Validation: operationId must reference an operation visible to the caller (else 404 ErrNotFound); the operation must be in a cancellable state — PENDING or RUNNING with a cancellable action — otherwise 409 ErrConflict (already terminal, or the action does not support cancellation); the Idempotency-Key header must be a UUID (else 422 ErrValidation). Async & state: Asynchronous; returns 202 with the Operation showing its current state (still PENDING/RUNNING with cancellation requested) → terminal state CANCELLED (or SUCCEEDED/FAILED if it won the race). Emits resource.updated frames with kind 'operation' and a { state } patch on each transition, plus frames for the target resource if its status reverts. Errors: 401 unauthenticated; 403 caller lacks write access to the operation's scope; 404 unknown/invisible operationId; 409 not cancellable (terminal or unsupported); 422 malformed Idempotency-Key; 500 internal. Idempotency/Concurrency: Idempotency-Key is optional (recommended); replaying the same key within 24h returns the original 202 body without re-issuing the cancel. Cancelling an operation for which cancellation was already requested is a no-op replay, not a conflict.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
operationId*stringIdentifier of the operation to cancel.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidCancellation accepted; the returned Operation reflects the in-flight state and will transition to CANCELLED.
application/json- response
A long-running operation record. GET /operations/{operationId} returns its current state.
id*stringOperation identifier, unique platform-wide.
action*stringCanonical action id that started this operation, e.g. compute.instance.create.
state*OperationStateState machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.
"PENDING""RUNNING""SUCCEEDED""FAILED""CANCELLED"resourceKind?|Kind of the target resource (matches RealtimeEvent.kind), null for resource-less actions.
resourceId?|Identifier of the target resource; null until the resource is allocated.
resourceName?|Human-readable name of the target resource captured when the operation was opened; null when unknown or the resource has been deleted (clients fall back to resourceId).
principalId?|Subject id (user id/email or service-account id) of the actor that initiated this operation, captured at the create chokepoint; null on internal/worker paths with no request-scoped principal or for historical rows. This is the real actor the Activity feed renders.
sourceIp?|Source IP address of the request that initiated this operation; null when unavailable (internal/worker paths, historical rows).
progressPercent?|Best-effort progress; null when the action does not report progress.
0 <= value <= 100error?|nullPopulated only when state is FAILED (or CANCELLED with partial rollback notes).
warning?|nullNon-fatal degradation recorded on an operation that still SUCCEEDED - the primary action completed but something explicitly requested could not be delivered (e.g. publicIp was requested at instance create but no floating IP could be assigned). On a CANCELLED create it reports that the provider resource had already been created and was kept (live and billed until deleted; details.disposition = left_in_place). Same code+message shape as error so clients render both uniformly; null when the operation ran without degradation.
startedAt?|When the worker began executing; null while PENDING.
finishedAt?|When a terminal state was reached; null while transitional.
createdAt*stringupdatedAt*stringcurl -X POST "https://example.com/operations/string/actions/cancel"{ "id": "string", "action": "string", "state": "PENDING", "resourceKind": "string", "resourceId": "string", "resourceName": "string", "principalId": "string", "sourceIp": "string", "progressPercent": 0, "error": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "warning": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "startedAt": "string", "finishedAt": "string", "createdAt": "string", "updatedAt": "string"}