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.
Attach a data disk to the instance
Attaches a data disk to the selected Instance ("Attach data disk" on the Disks tab of
the instance detail page). The backend provisions or binds the disk at the requested (or next free)
LUN with the requested storage type, size, and host-caching mode; once complete the disk appears
in the instance's data-disk list with its IOPS/throughput/encryption attributes.
Validation: instance must exist and be visible → 404 NOT_FOUND; current instance state must
permit attach (ACTIVE or STOPPED, not BUILD/DELETING) → 409 CONFLICT (also returned when the
requested lun is already occupied); name non-empty, type a supported storage type,
sizeGb a positive integer within plan limits, caching one of None/ReadOnly/ReadWrite →
422 VALIDATION_FAILED.
Async & state: Asynchronous (202) returning an Operation. The instance's taskState is set to
disk_attaching until the workflow ends in succeeded (disk visible at its LUN) or failed
(taskState cleared, disk not attached). resource.updated SSE frames with kind=instance carry
the taskState patches that drive UI refresh.
Errors: 401 UNAUTHENTICATED; 403 FORBIDDEN (caller lacks mutate rights in scope); 404
NOT_FOUND for unknown instance; 409 CONFLICT for state-disallowed attach or LUN collision; 422
VALIDATION_FAILED for bad disk parameters; 500 INTERNAL.
Idempotency/Concurrency: Idempotency-Key is optional (recommended); replaying the same
key returns the original
Operation instead of attaching a second disk. No If-Match — the action is keyed to the live
resource state, and concurrent conflicting actions resolve to 409.
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.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
instanceId*stringIdentifier of the compute instance.
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.
uuidapplication/json- body
Data disk to attach (mirrors the Disks tab data-disk attributes the UI displays).
name*stringDisplay name of the data volume created and attached.
^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$1 <= length <= 255type*stringStorage type, e.g. "Premium SSD" or "Standard SSD".
sizeGb*integer1 <= valuelun?integerOptional explicit LUN; the next free LUN is assigned when omitted.
0 <= valuecaching?stringHost caching mode for the attached disk.
"None""None""ReadOnly""ReadWrite"Attach accepted; returns the tracking Operation.
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/scopes/string/compute/instances/string/actions/attach" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "type": "string", "sizeGb": 1 }'{ "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"}