> ## Documentation Index > Fetch the complete documentation index at: https://docs.hiloop.ai/llms.txt > Use this file to discover all available pages before exploring further. # Patch v1sandboxes > Request a wake-or-return, seal-and-stop, TTL, or metadata update. Waking an already-running sandbox succeeds without changing it. The operation is asynchronous and returns 202 with Location and Retry-After; poll or long-poll GetSandbox for observed state. ## OpenAPI ````yaml /api-reference/openapi.yaml patch /v1/sandboxes/{id} openapi: 3.0.3 info: title: '' version: 0.0.1 servers: [] security: - bearerAuth: [] tags: - name: AnnotationSchemaService description: |- Org-scoped annotation-schema registry CRUD. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. Registration runs a backward-compatibility check against the latest live version and REJECTS an incompatible change (FAILED_PRECONDITION). These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: AnnotationService description: >- Typed annotation surface over the telemetry store: the annotate writes plus the one served annotation read every consumer shares. Organization scoping is enforced from request identity, not from the request body. Ingest of ordinary telemetry lives in TelemetryIngestService (telemetry.proto); the general event read surface lives in TelemetryQueryService (query.proto). - name: FeedbackService description: |- Product-feedback intake. The organization is derived from the caller's credential, never from the request body; a request with no org scope is UNAUTHENTICATED. Any org-scoped caller — a user session, a service key, or a sandbox-scoped credential — may submit feedback. - name: IdentityService description: Identity/health surface for the control-plane API. - name: MetaService description: Unauthenticated discovery surface for client-visible sibling service URLs. - name: ProjectService description: |- Org-scoped project CRUD. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: RunService description: |- Org-scoped access to runs and their lineage. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: SandboxService description: |- Org-scoped sandbox runtime API. The organization comes from the caller's credential. Org-scoped human and service credentials may use every route in their organization. A sandbox-scoped, lineage-confined credential may read its own sandbox and snapshot lineage and may exec or snapshot only that sandbox; it may not create, update, or delete sandboxes, delete snapshots, or exec into a sibling sandbox. State and verb rules are closed. Get and list serve every visible state. Failed and terminated rows remain available through GetSandbox for a server retention window, then return 404 not_found. Update to stopped is accepted from ready or running and is idempotent from stopped; update to running wakes stopped and is idempotent from running. A wake racing an in-flight stop waits for stop to win before wake proceeds. Workspace growth is accepted only for a stable durable sandbox and is idempotent for the same target; lifecycle mutation and growth never overlap. An undurable snapshot, including one whose request timed out, fences growth and cannot be deleted because its seal may still publish a late receipt; repeat the same snapshot request (and idempotency key, if supplied) to resolve its outcome. Delete is accepted once for a nonterminal sandbox; a second delete returns 404 not_found. Exec requires running and never wakes implicitly; any other non-quarantined state returns 409 sandbox_not_running. Snapshot is accepted from ready, running, or stopped; other non-quarantined states return 409 sandbox_not_ready. Every mutating verb on a quarantined sandbox returns 409 quarantined. A concurrent snapshot returns 409 snapshot_in_progress. Every error uses the flat {code, message, request_id} envelope. Stable route codes are invalid_argument (400), not_found (404), idempotency_conflict, name_conflict, sandbox_not_running, sandbox_not_ready, quarantined, snapshot_in_progress, snapshot_in_use, and snapshot_not_restorable, workspace_shrink_unsupported, and operation_conflict (409), unsupported_capability (422), quota_exceeded (429; details.quota.metric names the limit — sandboxes.running, sandboxes.total, or sandboxes.workspace_capacity_gib), and unavailable (503). Exec transport failures use spawn_failed or sandbox_stopped and discard any partial output; both mean the command did not run. A command that WAS dispatched but whose outcome could not be read is never an error: it returns 200 with the indeterminate outcome, alongside whatever partial output was collected, as a timeout does. Capability-receipt observation has no route in this version and is explicitly NOTIMPL; it is not inferred from Sandbox fields. - name: SecretService description: |- Org-scoped sandbox-secret management. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. Create/revoke/rotate require an owner/admin in the organization; these management RPCs never return the secret value. - name: TelemetryViewService description: >- Typed data-view surface over the telemetry store. Organization scoping is enforced from request identity, not from the request body. A data view's spec is the engine's `DataViewSpec` — a raw `Sql` `SELECT` — re-validated and compiled fresh on every run under the forced-organization safe-SQL gateway. The untrusted raw-SQL escape hatch is a separate `POST /v1/telemetry/sql` endpoint, intentionally kept off this typed wire. - name: UsageService description: Org-scoped product quota reads. - name: VolumeService description: |- Org-scoped volume CRUD. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: WorkloadService description: |- Org-scoped workload registry management. The organization is derived from the caller's credential; a request with no org scope is UNAUTHENTICATED. Registering and reading workloads is open to any org member. Setting a launch ACL and deleting a workload are operator actions and require an owner or admin in the organization. A sandbox-scoped credential may not register, delete, or manage workloads. paths: /v1/sandboxes/{id}: patch: tags: - SandboxService description: >- Request a wake-or-return, seal-and-stop, TTL, or metadata update. Waking an already-running sandbox succeeds without changing it. The operation is asynchronous and returns 202 with Location and Retry-After; poll or long-poll GetSandbox for observed state. operationId: SandboxService_UpdateSandbox parameters: - name: id in: path description: The sandbox id to update. required: true schema: type: string requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/UpdateSandboxStateRequest' - $ref: '#/components/schemas/UpdateSandboxTtlRequest' - $ref: '#/components/schemas/UpdateSandboxMetadataRequest' - $ref: '#/components/schemas/UpdateSandboxWorkspaceRequest' - $ref: '#/components/schemas/UpdateSandboxIdleTimeoutRequest' - $ref: '#/components/schemas/UpdateSandboxNetworkAccessRequest' required: true responses: '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/UpdateSandboxResponse' headers: Location: description: Canonical GetSandbox URL for the accepted sandbox. schema: type: string format: uri Retry-After: description: Minimum seconds to wait before reading observed state again. schema: type: integer format: uint32 minimum: 1 default: $ref: '#/components/responses/SandboxError' components: schemas: UpdateSandboxStateRequest: type: object properties: state: enum: - running - stopped type: string description: >- New desired lifecycle state. Omit it to leave lifecycle state unchanged. format: enum ttl_seconds: type: integer description: >- New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid. format: uint32 minimum: 1 metadata: type: object additionalProperties: type: string description: >- Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. maxProperties: 50 idle_timeout_seconds: type: integer description: >- New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged. format: uint32 minimum: 60 maximum: 86400 required: - state additionalProperties: false description: A sandbox update that includes a lifecycle transition. UpdateSandboxTtlRequest: type: object properties: state: enum: - running - stopped type: string description: >- New desired lifecycle state. Omit it to leave lifecycle state unchanged. format: enum ttl_seconds: type: integer description: >- New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid. format: uint32 minimum: 1 metadata: type: object additionalProperties: type: string description: >- Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. maxProperties: 50 idle_timeout_seconds: type: integer description: >- New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged. format: uint32 minimum: 60 maximum: 86400 required: - ttl_seconds additionalProperties: false description: A sandbox update that includes a new lifetime. UpdateSandboxMetadataRequest: type: object properties: state: enum: - running - stopped type: string description: >- New desired lifecycle state. Omit it to leave lifecycle state unchanged. format: enum ttl_seconds: type: integer description: >- New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid. format: uint32 minimum: 1 metadata: type: object additionalProperties: type: string description: >- Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. maxProperties: 50 idle_timeout_seconds: type: integer description: >- New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged. format: uint32 minimum: 60 maximum: 86400 required: - metadata additionalProperties: false description: A sandbox update that includes a metadata replacement. UpdateSandboxWorkspaceRequest: type: object properties: workspace_capacity_gib: type: integer description: >- New durable workspace capacity in whole GiB. It must be at least the current capacity; shrinking a workspace is unsupported. format: uint32 minimum: 1 required: - workspace_capacity_gib additionalProperties: false description: A grow-only durable workspace capacity update. UpdateSandboxIdleTimeoutRequest: type: object properties: state: enum: - running - stopped type: string description: >- New desired lifecycle state. Omit it to leave lifecycle state unchanged. format: enum ttl_seconds: type: integer description: >- New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid. format: uint32 minimum: 1 metadata: type: object additionalProperties: type: string description: >- Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. maxProperties: 50 idle_timeout_seconds: type: integer description: >- New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged. format: uint32 minimum: 60 maximum: 86400 required: - idle_timeout_seconds additionalProperties: false description: A sandbox update that includes a new idle-stop duration. UpdateSandboxNetworkAccessRequest: type: object properties: network_access: enum: - public - gateway_only - none type: string description: >- Replacement outbound-network posture. It must be the only update field and returns only after the deployment's policy controller selects the exact live pod incarnation. format: enum required: - network_access additionalProperties: false description: >- A retryable sandbox update that selects one closed outbound-network profile. UpdateSandboxResponse: type: object properties: id: type: string description: The sandbox id whose update was accepted. request_state: enum: - requested type: string description: >- The accepted mutation-request state, distinct from observed sandbox lifecycle state. format: enum network_access_receipt: allOf: - $ref: '#/components/schemas/SandboxNetworkAccessReceipt' description: Present after policy objects select the exact live pod incarnation. required: - id - request_state SandboxNetworkAccessReceipt: type: object properties: network_access: enum: - public - gateway_only - none type: string format: enum pod_uid: type: string pod_resource_version: type: string policies: type: array items: $ref: '#/components/schemas/SandboxNetworkPolicyObservation' description: >- Synchronous observation that policy objects select the exact live pod incarnation. This is not dataplane enforcement proof; phase-sensitive clients probe the network after it. SandboxErrorBody: type: object additionalProperties: false required: - code - message - request_id properties: code: type: string description: Stable machine-readable error code in snake_case. message: type: string description: Human-readable description; clients must not parse it. request_id: type: string description: Correlation id for support and diagnostics. SandboxNetworkPolicyObservation: type: object properties: policy_name: type: string policy_endpoint_name: type: string policy_endpoint_uid: type: string policy_endpoint_resource_version: type: string description: >- One policy-controller observation that the exact live pod is selected by an egress policy. responses: SandboxError: description: An error using the successor flat API error envelope. headers: Retry-After: description: Seconds to wait before retrying when the error is retryable. schema: type: integer format: uint64 content: application/json: schema: $ref: '#/components/schemas/SandboxErrorBody' securitySchemes: bearerAuth: type: http scheme: bearer description: Hiloop API key sent as an HTTP Bearer token. ````