> ## 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. # Get v1sandboxes 1 > Get a sandbox by its server-issued id. Clients accepting a name use a reference already in canonical sandbox id form (`sbx-` followed by 40 lowercase hex characters) as the id directly, resolve any other reference within the selected project through ListSandboxes' exact name filter, and call this route with the resulting id. A newly accepted sandbox is read through to runtime authority when its product record has not appeared yet, preserving read-your-writes. When wait_state and wait_timeout_seconds are supplied, it returns on that state or with the current row at deadline. ## OpenAPI ````yaml /api-reference/openapi.yaml get /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}: get: tags: - SandboxService description: >- Get a sandbox by its server-issued id. Clients accepting a name use a reference already in canonical sandbox id form (`sbx-` followed by 40 lowercase hex characters) as the id directly, resolve any other reference within the selected project through ListSandboxes' exact name filter, and call this route with the resulting id. A newly accepted sandbox is read through to runtime authority when its product record has not appeared yet, preserving read-your-writes. When wait_state and wait_timeout_seconds are supplied, it returns on that state or with the current row at deadline. operationId: SandboxService_GetSandbox parameters: - name: id in: path description: >- The server-issued sandbox id to fetch. Clients that accept names use a reference already in canonical sandbox id form (`sbx-` followed by 40 lowercase hex characters) as the id directly, and resolve any other reference through ListSandboxes' exact name filter. required: true schema: type: string - name: wait_state in: query description: >- Optional observed state to wait for. The request returns earlier if this state is observed. schema: enum: - requested - reserved - materializing - ready - running - stopped - terminating - failed - terminated - quarantined - attention type: string format: enum - name: wait_timeout_seconds in: query description: >- Long-poll bound in seconds, from 1 through 25. At the deadline, the current sandbox is returned. schema: type: integer format: uint32 minimum: 1 maximum: 25 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetSandboxResponse' default: $ref: '#/components/responses/SandboxError' components: schemas: GetSandboxResponse: type: object properties: sandbox: allOf: - $ref: '#/components/schemas/Sandbox' description: >- The requested sandbox, read through to runtime authority when the product record is not yet visible. required: - sandbox Sandbox: oneOf: - $ref: '#/components/schemas/SandboxFromImage' - $ref: '#/components/schemas/SandboxFromSnapshot' description: One organization-scoped sandbox and its observed state. 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. SandboxFromImage: type: object properties: id: type: string description: The stable sandbox id. state: enum: - requested - reserved - materializing - ready - running - stopped - terminating - failed - terminated - quarantined - attention type: string description: The current observed lifecycle state. format: enum image: type: string description: The OCI image reference used by a root sandbox. storage_class: enum: - standard - durable type: string description: The backing storage behavior selected at creation. format: enum expires_at: type: string description: >- The expiry time in RFC 3339 form. Omitted when the sandbox has no expiry. format: date-time endpoints: type: array items: $ref: '#/components/schemas/SandboxEndpoint' description: >- Authenticated private session-plane port endpoints. Empty until an endpoint is available; these are not public preview URLs. ssh: allOf: - $ref: '#/components/schemas/SandboxSshConnection' description: >- SSH connection information. Omitted until the sandbox can accept a session. lineage_path: type: string description: >- The immutable dotted lineage from the root sandbox to this sandbox. An image-created root uses its own id. A snapshot-created child appends its id to the parent snapshot's lineage_path. metadata: type: object additionalProperties: type: string description: >- Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. maxProperties: 50 created_at: type: string description: When the sandbox was accepted, in RFC 3339 form. format: date-time updated_at: type: string description: When the sandbox record last changed, in RFC 3339 form. format: date-time volumes: type: array items: $ref: '#/components/schemas/SandboxPinnedVolume' description: Admitted volumes with the immutable version pinned for this sandbox. state_reason: allOf: - $ref: '#/components/schemas/SandboxStateReason' description: >- Failure or quarantine reason. Omitted for lifecycle states that need no explanation. name: type: string description: >- Customer-supplied name, unique among the project's sandboxes that have not finished deleting. Omitted when no name was supplied at creation. minLength: 1 maxLength: 63 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$ resources: allOf: - $ref: '#/components/schemas/ResourceSpec' description: >- The compute shape resolved at admission, deployment defaults included. gpus is present only when the sandbox has accelerators. Omitted only on records that predate resource stamping. created_by: type: string description: >- Stable id of the principal that created the sandbox: the presented API key's id, or the session user's id. Empty when the creator was not recorded. last_activity: allOf: - $ref: '#/components/schemas/SandboxActivity' description: >- The most recent activity the service observed against this sandbox. Omitted when none has been observed since the sandbox was created. workload_image: type: string description: >- The OCI image the workload is actually running. For a root sandbox this repeats the source above; for one restored from a snapshot it is the resolved image, which is the snapshot's own unless the create named a different one. Read this rather than inferring an image from lineage — a restored sandbox does not necessarily run what its parent ran. workspace_capacity_gib: type: integer description: >- Durable workspace capacity in whole GiB. Omitted for standard storage and records that predate capacity stamping. format: uint32 placement_class: enum: - standard - non_preemptible type: string description: The immutable capacity posture selected at creation. format: enum idle_timeout_seconds: type: integer description: >- The resolved idle-stop duration in seconds. Omitted when idle stopping is disabled. format: uint32 idle_deadline: type: string description: >- The next idle-stop deadline in RFC 3339 form. Omitted while the sandbox is not running or the controller has not reported its activity clock yet. format: date-time shared_filesystems: type: array items: $ref: '#/components/schemas/SandboxSharedFilesystemMount' description: >- Shared filesystem selections admitted for this sandbox. These echo only the logical id, subdirectory, and guest path; deployment claim names and backend coordinates stay private. description: A root sandbox created from an OCI image. required: - id - state - storage_class - endpoints - lineage_path - metadata - created_at - updated_at - volumes - workload_image - placement_class - image additionalProperties: false SandboxFromSnapshot: type: object properties: id: type: string description: The stable sandbox id. state: enum: - requested - reserved - materializing - ready - running - stopped - terminating - failed - terminated - quarantined - attention type: string description: The current observed lifecycle state. format: enum snapshot_id: type: string description: The parent snapshot restored by a child sandbox. storage_class: enum: - standard - durable type: string description: The backing storage behavior selected at creation. format: enum expires_at: type: string description: >- The expiry time in RFC 3339 form. Omitted when the sandbox has no expiry. format: date-time endpoints: type: array items: $ref: '#/components/schemas/SandboxEndpoint' description: >- Authenticated private session-plane port endpoints. Empty until an endpoint is available; these are not public preview URLs. ssh: allOf: - $ref: '#/components/schemas/SandboxSshConnection' description: >- SSH connection information. Omitted until the sandbox can accept a session. lineage_path: type: string description: >- The immutable dotted lineage from the root sandbox to this sandbox. An image-created root uses its own id. A snapshot-created child appends its id to the parent snapshot's lineage_path. metadata: type: object additionalProperties: type: string description: >- Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. maxProperties: 50 created_at: type: string description: When the sandbox was accepted, in RFC 3339 form. format: date-time updated_at: type: string description: When the sandbox record last changed, in RFC 3339 form. format: date-time volumes: type: array items: $ref: '#/components/schemas/SandboxPinnedVolume' description: Admitted volumes with the immutable version pinned for this sandbox. state_reason: allOf: - $ref: '#/components/schemas/SandboxStateReason' description: >- Failure or quarantine reason. Omitted for lifecycle states that need no explanation. name: type: string description: >- Customer-supplied name, unique among the project's sandboxes that have not finished deleting. Omitted when no name was supplied at creation. minLength: 1 maxLength: 63 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$ resources: allOf: - $ref: '#/components/schemas/ResourceSpec' description: >- The compute shape resolved at admission, deployment defaults included. gpus is present only when the sandbox has accelerators. Omitted only on records that predate resource stamping. created_by: type: string description: >- Stable id of the principal that created the sandbox: the presented API key's id, or the session user's id. Empty when the creator was not recorded. last_activity: allOf: - $ref: '#/components/schemas/SandboxActivity' description: >- The most recent activity the service observed against this sandbox. Omitted when none has been observed since the sandbox was created. workload_image: type: string description: >- The OCI image the workload is actually running. For a root sandbox this repeats the source above; for one restored from a snapshot it is the resolved image, which is the snapshot's own unless the create named a different one. Read this rather than inferring an image from lineage — a restored sandbox does not necessarily run what its parent ran. workspace_capacity_gib: type: integer description: >- Durable workspace capacity in whole GiB. Omitted for standard storage and records that predate capacity stamping. format: uint32 placement_class: enum: - standard - non_preemptible type: string description: The immutable capacity posture selected at creation. format: enum idle_timeout_seconds: type: integer description: >- The resolved idle-stop duration in seconds. Omitted when idle stopping is disabled. format: uint32 idle_deadline: type: string description: >- The next idle-stop deadline in RFC 3339 form. Omitted while the sandbox is not running or the controller has not reported its activity clock yet. format: date-time shared_filesystems: type: array items: $ref: '#/components/schemas/SandboxSharedFilesystemMount' description: >- Shared filesystem selections admitted for this sandbox. These echo only the logical id, subdirectory, and guest path; deployment claim names and backend coordinates stay private. description: A child sandbox created from a snapshot. required: - id - state - storage_class - endpoints - lineage_path - metadata - created_at - updated_at - volumes - workload_image - placement_class - snapshot_id additionalProperties: false SandboxEndpoint: type: object properties: port: type: integer description: The guest TCP port exposed by this endpoint. format: uint32 minimum: 1 maximum: 65535 url: type: string description: The authenticated URL clients use to reach the port. format: uri description: A port endpoint assigned to a sandbox. required: - port - url SandboxSshConnection: type: object properties: host: type: string description: The session-plane hostname. port: type: integer description: The session-plane TCP port. format: uint32 minimum: 1 maximum: 65535 user: type: string description: The SSH username assigned to the sandbox session. description: SSH connection information for a ready or running sandbox. required: - host - port - user SandboxPinnedVolume: type: object properties: volume_id: type: string description: The mounted volume id. version: type: string description: The immutable volume version pinned at admission. target_path: type: string description: The absolute mount path inside the sandbox. name: type: string description: >- The mounted volume's name as resolved at admission. Empty when the volume had no name. description: >- A mounted volume as admitted on a sandbox, including the immutable pinned version. required: - volume_id - version - target_path SandboxStateReason: type: object properties: code: type: string description: Stable machine-readable reason code in snake_case. message: type: string description: Human-readable detail; clients must not parse it. description: A stable reason attached to a failed or quarantined lifecycle state. required: - code - message additionalProperties: false ResourceSpec: type: object properties: memory_mb: type: integer description: >- Requested memory in MB (mebibytes: 1024 MB = 1 GiB), from 1 through 1048576. Omit it to use the deployment default. format: uint32 minimum: 1 maximum: 1048576 gpus: allOf: - $ref: '#/components/schemas/ResourceSpec_Gpus' description: Requested accelerators. Omit it to request none. cpu_millis: type: integer description: >- Requested CPU in milliCPU, from 50 through 128000. 1000 milliCPU is one vCPU. Omit it to use the deployment default. format: uint32 minimum: 50 maximum: 128000 description: >- Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it. SandboxActivity: type: object properties: at: type: string description: >- When the activity was last observed, in RFC 3339 form. While a command is running or a session is held open, this advances periodically rather than only at the end. source: enum: - exec - session - update type: string description: What produced it. format: enum description: >- The most recent activity observed against a sandbox. Activity is what the service saw: a command submitted or still running, a session opened or still held, or a change to the sandbox itself. Work happening inside the sandbox that the service cannot see does not count. SandboxSharedFilesystemMount: type: object properties: filesystem_id: type: string description: Deployment-registered filesystem id. subdirectory: type: string description: >- Existing relative directory within the filesystem to mount. The directory must already exist when the sandbox pod starts. target_path: type: string description: >- Guest path at which the selected directory is mounted. It is either /workspace, which moves the sandbox's private durable workspace to /private, or a normalized path below /mnt, which leaves the private workspace at /workspace. Other paths are refused so shared storage cannot replace image executables, configuration, or platform-owned mounts. description: >- A deployment-registered shared filesystem mounted when the sandbox is created. The deployment resolves filesystem_id to its storage backend. Credentials and backend coordinates are never accepted from the sandbox caller or exposed inside the sandbox. ResourceSpec_Gpus: type: object properties: count: type: integer description: Integral accelerator count. format: uint32 models: type: array items: type: string description: >- Ordered fallback list of acceptable accelerator models. An empty list accepts any advertised model. description: Requested accelerators. 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. ````