> ## Documentation Index > Fetch the complete documentation index at: https://docs.akua.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a Cluster > Creates a hosted Cluster in a Region or attaches an existing one, and returns the creation Operation. It succeeds once the Cluster is ready. For an attached Cluster, issue the agent install command next. Retry with the same Idempotency-Key to get the same Cluster and Operation. ## OpenAPI ````yaml /openapi-public.json post /clusters openapi: 3.1.0 info: title: Akua API version: 1.0.0 description: >- Manage installs and their asynchronous operations. Authenticate with a session bearer token and select a Workspace using Akua-Context. contact: name: Akua API support email: support@akua.dev url: https://docs.akua.dev/ servers: - url: https://api.akua.dev/v1 security: [] tags: - name: operations - name: installs - name: Organizations - name: Billing accounts - name: workspaces - name: regions - name: Dashboard Overview - name: products - name: offers - name: Order Drafts - name: packages - name: Auth - name: API Tokens - name: Quota adjustments - name: Workspace services - name: Vault connections - name: clusters - name: Node pools - name: Nodes - name: machines - name: Sandboxes - name: OpenCode Servers - name: vaults - name: vaultSecrets paths: /clusters: post: tags: - clusters summary: Create a Cluster description: >- Creates a hosted Cluster in a Region or attaches an existing one, and returns the creation Operation. It succeeds once the Cluster is ready. For an attached Cluster, issue the agent install command next. Retry with the same Idempotency-Key to get the same Cluster and Operation. operationId: clusters.create parameters: - name: akua-context in: header schema: type: string minLength: 1 maxLength: 53 description: >- 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. examples: - ws_j572abc123def4 required: false - name: idempotency-key in: header schema: type: string minLength: 1 maxLength: 64 description: >- Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used. examples: - create-prod-2026-05-07 required: false requestBody: content: application/json: schema: $ref: '#/components/schemas/ClusterCreateBody' required: true responses: '202': description: Cluster creation accepted content: application/json: schema: $ref: '#/components/schemas/Operation' '400': description: The request is malformed. content: application/json: schema: $ref: '#/components/schemas/ApiBadRequest' '401': description: Missing, invalid or expired credential. content: application/json: schema: $ref: '#/components/schemas/ApiUnauthorized' '403': description: The credential may not act in this workspace. content: application/json: schema: $ref: '#/components/schemas/ApiForbidden' '404': description: The resource was not found in this workspace. content: application/json: schema: $ref: '#/components/schemas/ApiNotFound' '409': description: >- The request conflicts with existing resource state or immutable intent. | The resource changed since the etag the client sent; the current etag is in the metadata. | The idempotency key was already used for a different request. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ApiConflict' - $ref: '#/components/schemas/ApiPreconditionFailed' - $ref: '#/components/schemas/ApiIdempotencyConflict' '410': description: The resource is permanently unavailable. content: application/json: schema: $ref: '#/components/schemas/ApiGone' '422': description: The request is well-formed but cannot be processed. content: application/json: schema: $ref: '#/components/schemas/ApiUnprocessable' '429': description: The caller is over its per-minute budget. content: application/json: schema: $ref: '#/components/schemas/ApiTooManyRequests' '500': description: The server failed to handle the request. content: application/json: schema: $ref: '#/components/schemas/ApiInternalServerError' '502': description: An upstream provider failed. content: application/json: schema: $ref: '#/components/schemas/ApiExternalServiceError' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ApiServiceUnavailable' '504': description: An upstream provider did not answer in time. content: application/json: schema: $ref: '#/components/schemas/ApiGatewayTimeout' security: - BearerAuth: [] components: schemas: ClusterCreateBody: anyOf: - type: object properties: kind: type: string enum: - hosted description: >- Akua runs the control plane in the Region; you join your own servers. name: type: string minLength: 1 maxLength: 63 pattern: ^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$ description: A DNS label, unique in the Workspace. examples: - shop region_id: type: string minLength: 3 maxLength: 54 required: - kind - name - region_id additionalProperties: false - type: object properties: kind: type: string enum: - attached description: An existing Kubernetes cluster that runs the Akua cluster agent. name: type: string minLength: 1 maxLength: 63 pattern: ^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$ description: A DNS label, unique in the Workspace. examples: - shop access: $ref: '#/components/schemas/ClusterAccess' required: - kind - name - access additionalProperties: false Operation: type: object properties: id: type: string minLength: 2 maxLength: 192 workspace_id: anyOf: - type: string minLength: 1 maxLength: 53 - type: 'null' organization_id: anyOf: - type: string minLength: 1 maxLength: 54 - type: 'null' owner_type: type: string enum: - install - repository_change_request - repository - workspace - machine - cluster - node_pool - package - sandbox - opencode description: Domain entity collection the operation acts on. owner_id: type: string description: >- Prefixed ID of the entity this operation acts on. Prefix matches `owner_type` (`ws_`, `mch_`, `clu_`, `pkg_`, `inst_`, `rcr_`, `repo_`, `sbx_`, `oc_`); a node pool is `clu_/node_pools/`. parent_operation_id: anyOf: - type: string minLength: 2 maxLength: 192 - type: 'null' description: ID of the chained parent operation, when present. state: type: string enum: - RUNNING - SUCCEEDED - FAILED - CANCELLED description: Lifecycle state. Past-participle terminal states per AIP-216. done: type: boolean description: True iff state is a terminal value. html_url: type: string description: >- Deep link to the dashboard view of this operation's owning resource when available, otherwise the operation detail page. format: uri examples: - https://akua.dev/installs/inst_j572abc123def456?tab=operations maxLength: 2048 metadata: $ref: '#/components/schemas/OperationMetadata' response: $ref: '#/components/schemas/OperationResponse' error: anyOf: - type: object properties: code: type: integer message: type: string reason: type: string description: >- Why it failed, stable for clients to branch on. Node pool and Machine creates use `billing-required`, `quota-exceeded`, `service-disabled`, `capacity-unavailable`, `provider-refused`, `provider-unavailable` and `abandoned`; most Operations omit it. examples: - billing-required required: - message additionalProperties: false - type: 'null' description: Populated when `state` is `FAILED` or `CANCELLED`. last_error: anyOf: - type: object properties: message: type: string step_name: type: string required: - message additionalProperties: false - type: 'null' description: >- Latest error from any failed step. Populated even mid-flight; cleared when the step succeeds on retry. started_at: type: integer minimum: 0 description: Unix timestamp (seconds) completed_at: anyOf: - type: integer minimum: 0 - type: 'null' description: Unix timestamp (seconds) steps: type: array items: $ref: '#/components/schemas/OperationStep' required: - id - workspace_id - organization_id - owner_type - owner_id - parent_operation_id - state - done - html_url - metadata - response - error - last_error - started_at - completed_at additionalProperties: false ApiBadRequest: type: object properties: _tag: type: string enum: - Validation success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiUnauthorized: type: object properties: _tag: type: string enum: - Unauthorized success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiForbidden: type: object properties: _tag: type: string enum: - Forbidden success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiNotFound: type: object properties: _tag: type: string enum: - NotFound success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiConflict: type: object properties: _tag: type: string enum: - Conflict success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiPreconditionFailed: type: object properties: _tag: type: string enum: - PreconditionFailed success: type: boolean enum: - false errors: type: array prefixItems: - type: object properties: code: type: number enum: - 7006 message: type: string metadata: type: object properties: current_etag: type: string required: - current_etag allOf: - type: object additionalProperties: type: string required: - code - message - metadata additionalProperties: false maxItems: 1 minItems: 1 result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiIdempotencyConflict: type: object properties: _tag: type: string enum: - IdempotencyConflict success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiGone: type: object properties: _tag: type: string enum: - Gone success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiUnprocessable: type: object properties: _tag: type: string enum: - Unprocessable success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiTooManyRequests: type: object properties: _tag: type: string enum: - TooManyRequests success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiInternalServerError: type: object properties: _tag: type: string enum: - InternalServerError success: type: boolean enum: - false errors: type: array prefixItems: - type: object properties: code: type: number enum: - 7009 message: type: string enum: - Internal server error required: - code - message additionalProperties: false maxItems: 1 minItems: 1 result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiExternalServiceError: type: object properties: _tag: type: string enum: - ExternalServiceError success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiServiceUnavailable: type: object properties: _tag: type: string enum: - ServiceUnavailable success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiGatewayTimeout: type: object properties: _tag: type: string enum: - GatewayTimeout success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ClusterAccess: oneOf: - type: object properties: kind: type: string enum: - cluster required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - namespaces namespaces: type: array prefixItems: - type: string minLength: 1 maxLength: 63 minItems: 1 items: type: string minLength: 1 maxLength: 63 maxItems: 256 required: - kind - namespaces additionalProperties: false OperationMetadata: oneOf: - type: object properties: type: type: string enum: - machine.create workspace_id: type: string minLength: 1 maxLength: 53 cluster_id: type: string minLength: 1 maxLength: 54 compute_config_id: type: string minLength: 1 maxLength: 54 instance_type: type: string managed: type: boolean request_fingerprint: type: string minLength: 1 required: - type - workspace_id - instance_type - managed - request_fingerprint additionalProperties: false - type: object properties: type: type: string enum: - machine.delete workspace_id: type: string minLength: 1 maxLength: 53 machine_id: type: string minLength: 1 maxLength: 54 request_fingerprint: type: string minLength: 1 required: - type - workspace_id - machine_id - request_fingerprint additionalProperties: false - type: object properties: type: type: string enum: - machine.suspend workspace_id: type: string minLength: 1 maxLength: 53 machine_id: type: string minLength: 1 maxLength: 54 request_fingerprint: type: string minLength: 1 required: - type - workspace_id - machine_id - request_fingerprint additionalProperties: false - type: object properties: type: type: string enum: - machine.resume workspace_id: type: string minLength: 1 maxLength: 53 machine_id: type: string minLength: 1 maxLength: 54 request_fingerprint: type: string minLength: 1 required: - type - workspace_id - machine_id - request_fingerprint additionalProperties: false - type: object properties: type: type: string enum: - cluster.delete cluster_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.create workspace_id: type: string minLength: 1 maxLength: 53 cluster_id: type: string description: >- ID of the new cluster. Set once the cluster record exists, before provisioning finishes. minLength: 1 maxLength: 54 name: type: string kind: type: string enum: - hosted - attached region_id: anyOf: - type: string minLength: 1 maxLength: 54 - type: 'null' description: The Region of a hosted Cluster; null for an attached one. required: - type - workspace_id - name - kind - region_id additionalProperties: false - type: object properties: type: type: string enum: - node_pool.create - node_pool.set_size - node_pool.delete workspace_id: type: string minLength: 1 maxLength: 53 cluster_id: type: string minLength: 1 maxLength: 54 node_pool_id: type: string minLength: 1 maxLength: 40 node_count: anyOf: - type: integer - type: 'null' description: The size the Operation moves the pool to; null for a deletion. required: - type - workspace_id - cluster_id - node_pool_id - node_count additionalProperties: false - type: object properties: type: type: string enum: - cluster.node.remove workspace_id: type: string minLength: 1 maxLength: 53 cluster_id: type: string minLength: 1 maxLength: 54 node_name: type: string minLength: 1 maxLength: 253 required: - type - workspace_id - cluster_id - node_name additionalProperties: false - type: object properties: type: type: string enum: - cluster.suspend cluster_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.resume cluster_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.capabilities.refresh cluster_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.capability.ensure cluster_id: type: string minLength: 1 maxLength: 54 capability: type: string minLength: 1 required: - type - cluster_id - capability additionalProperties: false - type: object properties: type: type: string enum: - cluster.worker_bootstrap.revoke cluster_id: type: string minLength: 1 maxLength: 54 worker_bootstrap_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id - worker_bootstrap_id additionalProperties: false - type: object properties: type: type: string enum: - install.create idempotency_key: type: string workspace_id: type: string minLength: 1 maxLength: 53 product_id: type: string minLength: 1 maxLength: 55 required: - type - idempotency_key - workspace_id additionalProperties: false - type: object properties: type: type: string enum: - install.render install_id: type: string minLength: 1 maxLength: 55 trigger_commit_sha: type: string required: - type - install_id additionalProperties: false - type: object properties: type: type: string enum: - install.delete install_id: type: string minLength: 1 maxLength: 55 required: - type - install_id additionalProperties: false - type: object properties: type: type: string enum: - preview_hostname.bind_pinned install_id: type: string minLength: 1 maxLength: 55 render_id: type: string minLength: 1 maxLength: 54 protocol: type: string enum: - http - websocket - grpc routing_mode: type: string enum: - through_dispatcher - bypass_dispatcher idempotency_key: type: string required: - type - install_id - render_id - protocol - routing_mode - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - preview_hostname.bind_floating install_id: type: string minLength: 1 maxLength: 55 track: type: string minLength: 1 maxLength: 100 render_id: type: string minLength: 1 maxLength: 54 protocol: type: string enum: - http - websocket - grpc routing_mode: type: string enum: - through_dispatcher - bypass_dispatcher idempotency_key: type: string required: - type - install_id - track - render_id - protocol - routing_mode - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - preview_hostname.delete install_id: type: string minLength: 1 maxLength: 55 preview_hostname_id: type: string minLength: 1 maxLength: 54 if_match: type: string idempotency_key: type: string required: - type - install_id - preview_hostname_id - if_match - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - workspace.delete workspace_id: type: string minLength: 1 maxLength: 53 required: - type - workspace_id additionalProperties: false - type: object properties: type: type: string enum: - workspace.subscription.cancel workspace_id: type: string minLength: 1 maxLength: 53 mode: type: string enum: - period_end required: - type - workspace_id - mode additionalProperties: false - type: object properties: type: type: string enum: - workspace.subdomain.set_name workspace_id: type: string minLength: 1 maxLength: 53 name: type: string minLength: 1 maxLength: 63 idempotency_key: type: string required: - type - workspace_id - name - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - custom_domain.create workspace_id: type: string minLength: 1 maxLength: 53 hostname: type: string minLength: 1 maxLength: 253 target: oneOf: - type: object properties: kind: type: string enum: - install install_id: type: string minLength: 1 maxLength: 55 required: - kind - install_id additionalProperties: false - type: object properties: kind: type: string enum: - cluster cluster_id: type: string minLength: 1 maxLength: 54 required: - kind - cluster_id additionalProperties: false - type: object properties: kind: type: string enum: - external endpoint: type: string format: uri mtls_secret_id: type: string minLength: 1 maxLength: 54 required: - kind - endpoint additionalProperties: false protocol: type: string enum: - http - websocket - grpc routing_mode: type: string enum: - through_dispatcher - bypass_dispatcher idempotency_key: type: string required: - type - workspace_id - hostname - target - protocol - routing_mode - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - custom_domain.update workspace_id: type: string minLength: 1 maxLength: 53 custom_domain_id: type: string minLength: 1 maxLength: 54 target: oneOf: - type: object properties: kind: type: string enum: - install install_id: type: string minLength: 1 maxLength: 55 required: - kind - install_id additionalProperties: false - type: object properties: kind: type: string enum: - cluster cluster_id: type: string minLength: 1 maxLength: 54 required: - kind - cluster_id additionalProperties: false - type: object properties: kind: type: string enum: - external endpoint: type: string format: uri mtls_secret_id: type: string minLength: 1 maxLength: 54 required: - kind - endpoint additionalProperties: false protocol: type: string enum: - http - websocket - grpc routing_mode: type: string enum: - through_dispatcher - bypass_dispatcher if_match: type: string idempotency_key: type: string required: - type - workspace_id - custom_domain_id - if_match - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - custom_domain.delete workspace_id: type: string minLength: 1 maxLength: 53 custom_domain_id: type: string minLength: 1 maxLength: 54 if_match: type: string idempotency_key: type: string required: - type - workspace_id - custom_domain_id - if_match - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - cloudflare.private_origin_route.prepare workspace_id: type: string minLength: 1 maxLength: 53 cluster_id: type: string minLength: 1 maxLength: 54 route_intent_id: type: string minLength: 1 maxLength: 54 required: - type - workspace_id - cluster_id - route_intent_id additionalProperties: false - type: object properties: type: type: string enum: - cloudflare.private_origin_route.release workspace_id: type: string minLength: 1 maxLength: 53 route_intent_id: type: string minLength: 1 maxLength: 54 required: - type - workspace_id - route_intent_id additionalProperties: false - type: object properties: type: type: string enum: - package.create idempotency_key: type: string workspace_id: type: string minLength: 1 maxLength: 53 name: type: string required: - type - idempotency_key - workspace_id - name additionalProperties: false - type: object properties: type: type: string enum: - package.version.publish_hosted idempotency_key: type: string workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 request_fingerprint: type: string minLength: 1 required: - type - idempotency_key - workspace_id - package_id - request_fingerprint additionalProperties: false - type: object properties: type: type: string enum: - package.version.publish_local_chart idempotency_key: type: string workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 required: - type - idempotency_key - workspace_id - package_id additionalProperties: false - type: object properties: type: type: string enum: - package.version.publish idempotency_key: type: string workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 version: type: string minLength: 1 maxLength: 128 required: - type - idempotency_key - workspace_id - package_id - version additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.create workspace_id: type: string minLength: 1 maxLength: 53 parent_repository_id: type: string minLength: 1 maxLength: 55 created_by_kind: type: string enum: - agent - wizard - user required: - type - workspace_id - parent_repository_id - created_by_kind additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.accept repository_change_request_id: type: string minLength: 1 maxLength: 54 user_id: type: string required: - type - repository_change_request_id - user_id additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.reject repository_change_request_id: type: string minLength: 1 maxLength: 54 user_id: type: string reason: type: string required: - type - repository_change_request_id - user_id - reason additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.withdraw repository_change_request_id: type: string minLength: 1 maxLength: 54 user_id: type: string required: - type - repository_change_request_id - user_id additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.expire repository_change_request_id: type: string minLength: 1 maxLength: 54 required: - type - repository_change_request_id additionalProperties: false - type: object properties: type: type: string enum: - opencode.suspend workspace_id: type: string minLength: 1 maxLength: 53 opencode_id: type: string minLength: 1 maxLength: 70 idempotency_key: type: string reason: type: string enum: - manual - workspace_deleted required: - type - workspace_id - opencode_id - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - opencode.resume workspace_id: type: string minLength: 1 maxLength: 53 opencode_id: type: string minLength: 1 maxLength: 70 idempotency_key: type: string reason: type: string enum: - manual - workspace_deleted required: - type - workspace_id - opencode_id - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - opencode.delete workspace_id: type: string minLength: 1 maxLength: 53 opencode_id: type: string minLength: 1 maxLength: 70 idempotency_key: type: string reason: type: string enum: - manual - workspace_deleted required: - type - workspace_id - opencode_id - idempotency_key additionalProperties: false - type: object properties: type: type: string enum: - repository.delete repository_id: type: string minLength: 1 maxLength: 55 required: - type - repository_id additionalProperties: false - type: object properties: type: type: string enum: - sandbox.create workspace_id: type: string minLength: 1 maxLength: 53 sandbox_id: type: string minLength: 1 maxLength: 54 source_sandbox_id: type: string description: Set when the sandbox is a fork of another sandbox. minLength: 1 maxLength: 54 required: - type - workspace_id - sandbox_id additionalProperties: false - type: object properties: type: type: string enum: - sandbox.suspend workspace_id: type: string minLength: 1 maxLength: 53 sandbox_id: type: string minLength: 1 maxLength: 54 reason: type: string enum: - manual - idle description: '`idle`: the sandbox suspended itself after its idle timeout.' required: - type - workspace_id - sandbox_id - reason additionalProperties: false - type: object properties: type: type: string enum: - sandbox.resume workspace_id: type: string minLength: 1 maxLength: 53 sandbox_id: type: string minLength: 1 maxLength: 54 required: - type - workspace_id - sandbox_id additionalProperties: false - type: object properties: type: type: string enum: - sandbox.delete workspace_id: type: string minLength: 1 maxLength: 53 sandbox_id: type: string minLength: 1 maxLength: 54 reason: type: string enum: - manual - orphaned - workspace_deleted description: >- `orphaned`: nobody had access to the sandbox for 7 days. `workspace_deleted`: its workspace is being deleted. required: - type - workspace_id - sandbox_id - reason additionalProperties: false - type: object properties: type: type: string enum: - connect.vault.delete workspace_id: type: string minLength: 1 maxLength: 53 vault_id: type: string minLength: 1 maxLength: 54 required: - type - workspace_id - vault_id additionalProperties: false - type: object properties: type: type: string enum: - connect.connection.revoke workspace_id: type: string minLength: 1 maxLength: 53 vault_id: type: string minLength: 1 maxLength: 54 connection_id: type: string minLength: 1 maxLength: 55 required: - type - workspace_id - vault_id - connection_id additionalProperties: false OperationResponse: anyOf: - type: object properties: type: type: string enum: - machine.create machine_id: type: string minLength: 1 maxLength: 54 provider_id: type: string required: - type - machine_id - provider_id additionalProperties: false - type: object properties: type: type: string enum: - machine.delete machine_id: type: string minLength: 1 maxLength: 54 required: - type - machine_id additionalProperties: false - type: object properties: type: type: string enum: - machine.suspend machine_id: type: string minLength: 1 maxLength: 54 suspension_id: type: string minLength: 1 maxLength: 54 required: - type - machine_id - suspension_id additionalProperties: false - type: object properties: type: type: string enum: - machine.resume machine_id: type: string minLength: 1 maxLength: 54 required: - type - machine_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.delete cluster_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.create cluster_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.node.remove cluster_id: type: string minLength: 1 maxLength: 54 node_name: type: string minLength: 1 maxLength: 253 required: - type - cluster_id - node_name additionalProperties: false - type: object properties: type: type: string enum: - node_pool.create - node_pool.set_size - node_pool.delete cluster_id: type: string minLength: 1 maxLength: 54 node_pool_id: type: string minLength: 1 maxLength: 40 required: - type - cluster_id - node_pool_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.suspend cluster_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.resume cluster_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.capabilities.refresh cluster_id: type: string minLength: 1 maxLength: 54 required: - type - cluster_id additionalProperties: false - type: object properties: type: type: string enum: - cluster.capability.ensure cluster_id: type: string minLength: 1 maxLength: 54 capability: type: string minLength: 1 required: - type - cluster_id - capability additionalProperties: false - type: object properties: type: type: string enum: - cluster.worker_bootstrap.revoke note: type: string required: - type additionalProperties: false - type: object properties: type: type: string enum: - install.create install_id: type: string minLength: 1 maxLength: 55 argo_app_name: type: string argo_app_namespace: type: string required: - type - install_id - argo_app_name - argo_app_namespace additionalProperties: false - type: object properties: type: type: string enum: - install.create install_id: type: string minLength: 1 maxLength: 55 sandbox_skipped: type: boolean enum: - true required: - type - install_id - sandbox_skipped additionalProperties: false - type: object properties: type: type: string enum: - install.render install_render_id: type: string minLength: 1 maxLength: 54 repository_id: type: string minLength: 1 maxLength: 55 commit_sha: type: string render_hash: type: string skipped: type: boolean required: - type - install_render_id - repository_id - render_hash - skipped additionalProperties: false - type: object properties: type: type: string enum: - install.delete argo_app_deleted: type: boolean repo_purged: type: boolean required: - type - argo_app_deleted - repo_purged additionalProperties: false - type: object properties: type: type: string enum: - preview_hostname.bind_pinned install_id: type: string minLength: 1 maxLength: 55 preview_hostname_id: type: string minLength: 1 maxLength: 54 hostname: type: string minLength: 1 maxLength: 253 required: - type - install_id - preview_hostname_id - hostname additionalProperties: false - type: object properties: type: type: string enum: - preview_hostname.bind_floating install_id: type: string minLength: 1 maxLength: 55 preview_hostname_id: type: string minLength: 1 maxLength: 54 hostname: type: string minLength: 1 maxLength: 253 required: - type - install_id - preview_hostname_id - hostname additionalProperties: false - type: object properties: type: type: string enum: - preview_hostname.delete install_id: type: string minLength: 1 maxLength: 55 preview_hostname_id: type: string minLength: 1 maxLength: 54 hostname: type: string minLength: 1 maxLength: 253 required: - type - install_id - preview_hostname_id - hostname additionalProperties: false - type: object properties: type: type: string enum: - workspace.delete workspace_id: type: string minLength: 1 maxLength: 53 required: - type - workspace_id additionalProperties: false - type: object properties: type: type: string enum: - workspace.subscription.cancel subscription_id: type: string cancel_at: type: integer minimum: 0 description: Unix timestamp (seconds) required: - type - subscription_id - cancel_at additionalProperties: false - type: object properties: type: type: string enum: - workspace.subdomain.set_name workspace_id: type: string minLength: 1 maxLength: 53 workspace_subdomain_id: type: string minLength: 1 maxLength: 54 fqdn: type: string minLength: 1 maxLength: 253 required: - type - workspace_id - workspace_subdomain_id - fqdn additionalProperties: false - type: object properties: type: type: string enum: - custom_domain.create workspace_id: type: string minLength: 1 maxLength: 53 custom_domain_id: type: string minLength: 1 maxLength: 54 hostname: type: string minLength: 1 maxLength: 253 required: - type - workspace_id - custom_domain_id - hostname additionalProperties: false - type: object properties: type: type: string enum: - custom_domain.update workspace_id: type: string minLength: 1 maxLength: 53 custom_domain_id: type: string minLength: 1 maxLength: 54 hostname: type: string minLength: 1 maxLength: 253 required: - type - workspace_id - custom_domain_id - hostname additionalProperties: false - type: object properties: type: type: string enum: - custom_domain.delete workspace_id: type: string minLength: 1 maxLength: 53 custom_domain_id: type: string minLength: 1 maxLength: 54 hostname: type: string minLength: 1 maxLength: 253 required: - type - workspace_id - custom_domain_id - hostname additionalProperties: false - type: object properties: type: type: string enum: - cloudflare.private_origin_route.prepare origin_route_id: type: string minLength: 1 maxLength: 54 required: - type - origin_route_id additionalProperties: false - type: object properties: type: type: string enum: - cloudflare.private_origin_route.release route_intent_id: type: string minLength: 1 maxLength: 54 required: - type - route_intent_id additionalProperties: false - type: object properties: type: type: string enum: - package.create package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 repository_id: type: string minLength: 1 maxLength: 55 required: - type - package_id - package_version_id - repository_id additionalProperties: false - type: object properties: type: type: string enum: - package.version.publish_hosted package_version_id: type: string minLength: 1 maxLength: 55 required: - type - package_version_id additionalProperties: false - type: object properties: type: type: string enum: - package.version.publish_local_chart package_version_id: type: string minLength: 1 maxLength: 55 required: - type - package_version_id additionalProperties: false - type: object properties: type: type: string enum: - package.version.publish package_version_id: type: string minLength: 1 maxLength: 55 artifact_digest: type: string required: - type - package_version_id - artifact_digest additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.create repository_change_request_id: type: string minLength: 1 maxLength: 54 fork_repository_id: type: string minLength: 1 maxLength: 55 expires_at: type: integer minimum: 0 description: Unix timestamp (seconds) required: - type - repository_change_request_id - fork_repository_id - expires_at additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.accept merged_at: type: integer minimum: 0 description: Unix timestamp (seconds) triggered_install_render: type: boolean required: - type - merged_at - triggered_install_render additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.reject rejected_at: type: integer minimum: 0 description: Unix timestamp (seconds) required: - type - rejected_at additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.withdraw withdrawn_at: type: integer minimum: 0 description: Unix timestamp (seconds) required: - type - withdrawn_at additionalProperties: false - type: object properties: type: type: string enum: - repository_change_request.expire expired: type: boolean required: - type - expired additionalProperties: false - type: object properties: type: type: string enum: - opencode.suspend opencode_id: type: string minLength: 1 maxLength: 70 state: type: string enum: - SUSPENDED required: - type - opencode_id - state additionalProperties: false - type: object properties: type: type: string enum: - opencode.resume opencode_id: type: string minLength: 1 maxLength: 70 state: type: string enum: - ACTIVE required: - type - opencode_id - state additionalProperties: false - type: object properties: type: type: string enum: - opencode.delete opencode_id: type: string minLength: 1 maxLength: 70 state: type: string enum: - DELETED required: - type - opencode_id - state additionalProperties: false - type: object properties: type: type: string enum: - repository.delete purged_at: type: integer minimum: 0 description: Unix timestamp (seconds) required: - type - purged_at additionalProperties: false - type: object properties: type: type: string enum: - sandbox.create sandbox_id: type: string minLength: 1 maxLength: 54 required: - type - sandbox_id additionalProperties: false - type: object properties: type: type: string enum: - sandbox.suspend sandbox_id: type: string minLength: 1 maxLength: 54 required: - type - sandbox_id additionalProperties: false - type: object properties: type: type: string enum: - sandbox.resume sandbox_id: type: string minLength: 1 maxLength: 54 required: - type - sandbox_id additionalProperties: false - type: object properties: type: type: string enum: - sandbox.delete sandbox_id: type: string minLength: 1 maxLength: 54 required: - type - sandbox_id additionalProperties: false - type: object properties: type: type: string enum: - connect.vault.delete vault_id: type: string minLength: 1 maxLength: 54 required: - type - vault_id additionalProperties: false - type: object properties: type: type: string enum: - connect.connection.revoke connection_id: type: string minLength: 1 maxLength: 55 required: - type - connection_id additionalProperties: false - type: 'null' description: >- Populated only when `done && state === "SUCCEEDED"`. Discriminated by `type`. OperationStep: type: object properties: name: type: string description: User-visible milestone name. status: type: string enum: - pending - running - completed - failed - skipped description: Step lifecycle state. execution_type: type: string enum: - system - user - approval - skipped description: >- Step execution kind. `user`/`approval` mean the workflow is blocked on a human action. Internal bookkeeping steps are filtered from public responses. started_at: type: integer minimum: 0 description: Unix timestamp (seconds) completed_at: anyOf: - type: integer minimum: 0 - type: 'null' description: Unix timestamp (seconds) error_message: anyOf: - type: string - type: 'null' retryable: type: boolean skippable: type: boolean required: - name - status - execution_type - started_at - completed_at - error_message - retryable - skippable additionalProperties: false ApiErrorEntry: type: object properties: code: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Machine-readable error code examples: - 7002 message: type: string description: Human-readable error message examples: - Resource not found path: type: array items: type: string description: Field path that caused the error, when applicable examples: - - body - name metadata: type: object additionalProperties: type: string required: - code - message additionalProperties: false securitySchemes: BearerAuth: description: Bearer token for the authenticated caller. type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.