> ## 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. # Python SDK > Generated API reference for the hiloop Python SDK — operations and models. This is the exhaustive listing of the `hiloop` package: its generated operations and models, plus the focused `Sandbox` lifecycle and streaming helpers shipped with them. To install the SDK, configure a client, and make your first call, start with [Use the SDKs](/guides/using-the-sdks). Each operation module exposes `sync` / `sync_detailed` / `asyncio` / `asyncio_detailed` functions — import the module and call one with `client=` and a request body; request and response bodies are the typed models below. For HTTP paths and status codes, see the [API reference](/api-reference). ## Client A client library for accessing ### Client ```python theme={null} @define class Client() ``` A class for keeping track of data related to the API The following are accepted as keyword arguments and will be used to construct httpx Clients internally: `base_url`: The base URL for the API, all requests are made to a relative path to this URL `cookies`: A dictionary of cookies to be sent with every request `headers`: A dictionary of headers to be sent with every request `timeout`: The maximum amount of a time a request can take. API functions will raise httpx.TimeoutException if this is exceeded. `verify_ssl`: Whether or not to verify the SSL certificate of the API server. This should be True in production, but can be set to False for testing purposes. `follow_redirects`: Whether or not to follow redirects. Default value is False. `httpx_args`: A dictionary of additional arguments to be passed to the `httpx.Client` and `httpx.AsyncClient` constructor. **Attributes**: * `raise_on_unexpected_status` - Whether or not to raise an errors.UnexpectedStatus if the API returns a status code that was not documented in the source OpenAPI document. Can also be provided as a keyword argument to the constructor. ##### with\_headers ```python theme={null} def with_headers(headers: dict[str, str]) -> "Client" ``` Get a new client matching this one with additional headers ##### with\_cookies ```python theme={null} def with_cookies(cookies: dict[str, str]) -> "Client" ``` Get a new client matching this one with additional cookies ##### with\_timeout ```python theme={null} def with_timeout(timeout: httpx.Timeout) -> "Client" ``` Get a new client matching this one with a new timeout configuration ##### set\_httpx\_client ```python theme={null} def set_httpx_client(client: httpx.Client) -> "Client" ``` Manually set the underlying httpx.Client **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout. ##### get\_httpx\_client ```python theme={null} def get_httpx_client() -> httpx.Client ``` Get the underlying httpx.Client, constructing a new one if not previously set ##### \_\_enter\_\_ ```python theme={null} def __enter__() -> "Client" ``` Enter a context manager for self.client—you cannot enter twice (see httpx docs) ##### \_\_exit\_\_ ```python theme={null} def __exit__(*args: Any, **kwargs: Any) -> None ``` Exit a context manager for internal httpx.Client (see httpx docs) ##### set\_async\_httpx\_client ```python theme={null} def set_async_httpx_client(async_client: httpx.AsyncClient) -> "Client" ``` Manually set the underlying httpx.AsyncClient **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout. ##### get\_async\_httpx\_client ```python theme={null} def get_async_httpx_client() -> httpx.AsyncClient ``` Get the underlying httpx.AsyncClient, constructing a new one if not previously set ##### \_\_aenter\_\_ ```python theme={null} async def __aenter__() -> "Client" ``` Enter a context manager for underlying httpx.AsyncClient—you cannot enter twice (see httpx docs) ##### \_\_aexit\_\_ ```python theme={null} async def __aexit__(*args: Any, **kwargs: Any) -> None ``` Exit a context manager for underlying httpx.AsyncClient (see httpx docs) ### AuthenticatedClient ```python theme={null} @define class AuthenticatedClient() ``` A Client which has been authenticated for use on secured endpoints The following are accepted as keyword arguments and will be used to construct httpx Clients internally: `base_url`: The base URL for the API, all requests are made to a relative path to this URL `cookies`: A dictionary of cookies to be sent with every request `headers`: A dictionary of headers to be sent with every request `timeout`: The maximum amount of a time a request can take. API functions will raise httpx.TimeoutException if this is exceeded. `verify_ssl`: Whether or not to verify the SSL certificate of the API server. This should be True in production, but can be set to False for testing purposes. `follow_redirects`: Whether or not to follow redirects. Default value is False. `httpx_args`: A dictionary of additional arguments to be passed to the `httpx.Client` and `httpx.AsyncClient` constructor. **Attributes**: * `raise_on_unexpected_status` - Whether or not to raise an errors.UnexpectedStatus if the API returns a status code that was not documented in the source OpenAPI document. Can also be provided as a keyword argument to the constructor. * `token` - The token to use for authentication * `prefix` - The prefix to use for the Authorization header * `auth_header_name` - The name of the Authorization header ##### with\_headers ```python theme={null} def with_headers(headers: dict[str, str]) -> "AuthenticatedClient" ``` Get a new client matching this one with additional headers ##### with\_cookies ```python theme={null} def with_cookies(cookies: dict[str, str]) -> "AuthenticatedClient" ``` Get a new client matching this one with additional cookies ##### with\_timeout ```python theme={null} def with_timeout(timeout: httpx.Timeout) -> "AuthenticatedClient" ``` Get a new client matching this one with a new timeout configuration ##### set\_httpx\_client ```python theme={null} def set_httpx_client(client: httpx.Client) -> "AuthenticatedClient" ``` Manually set the underlying httpx.Client **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout. ##### get\_httpx\_client ```python theme={null} def get_httpx_client() -> httpx.Client ``` Get the underlying httpx.Client, constructing a new one if not previously set ##### \_\_enter\_\_ ```python theme={null} def __enter__() -> "AuthenticatedClient" ``` Enter a context manager for self.client—you cannot enter twice (see httpx docs) ##### \_\_exit\_\_ ```python theme={null} def __exit__(*args: Any, **kwargs: Any) -> None ``` Exit a context manager for internal httpx.Client (see httpx docs) ##### set\_async\_httpx\_client ```python theme={null} def set_async_httpx_client( async_client: httpx.AsyncClient) -> "AuthenticatedClient" ``` Manually set the underlying httpx.AsyncClient **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout. ##### get\_async\_httpx\_client ```python theme={null} def get_async_httpx_client() -> httpx.AsyncClient ``` Get the underlying httpx.AsyncClient, constructing a new one if not previously set ##### \_\_aenter\_\_ ```python theme={null} async def __aenter__() -> "AuthenticatedClient" ``` Enter a context manager for underlying httpx.AsyncClient—you cannot enter twice (see httpx docs) ##### \_\_aexit\_\_ ```python theme={null} async def __aexit__(*args: Any, **kwargs: Any) -> None ``` Exit a context manager for underlying httpx.AsyncClient (see httpx docs) Contains shared errors types that can be raised from API functions ### UnexpectedStatus ```python theme={null} class UnexpectedStatus(Exception) ``` Raised by api functions when the response status an undocumented status and Client.raise\_on\_unexpected\_status is True Typed helpers for hiloop's Server-Sent Events surfaces. ### SseEvent ```python theme={null} @define(frozen=True) class SseEvent(Generic[T]) ``` One decoded SSE frame, including its resume metadata. ##### tail\_run ```python theme={null} def tail_run( *, client: SdkClient, run_id: str, lineage_path: str | None = None, signal: str | None = None, cursor: str | None = None ) -> Iterator[SseEvent[dict[str, Any]]] | ErrorBody | None ``` Tail canonical telemetry events for a run, including each resume cursor. ##### tail\_run\_async ```python theme={null} async def tail_run_async( *, client: SdkClient, run_id: str, lineage_path: str | None = None, signal: str | None = None, cursor: str | None = None ) -> AsyncIterator[SseEvent[dict[str, Any]]] | ErrorBody | None ``` Tail canonical telemetry events with the generated client's async transport. Contains some shared types for properties ### File ```python theme={null} @define class File() ``` Contains information for file uploads ##### to\_tuple ```python theme={null} def to_tuple() -> FileTypes ``` Return a tuple representation that httpx will accept for multipart/form-data ### Response ```python theme={null} @define class Response(Generic[T]) ``` A response from an endpoint ## Operations ### Sandboxes & runtime * `hiloop.api.sandbox_service.sandbox_service_create_sandbox` * `hiloop.api.sandbox_service.sandbox_service_create_sandbox_snapshot` * `hiloop.api.sandbox_service.sandbox_service_delete_sandbox` * `hiloop.api.sandbox_service.sandbox_service_delete_sandbox_snapshot` * `hiloop.api.sandbox_service.sandbox_service_exec_sandbox` * `hiloop.api.sandbox_service.sandbox_service_get_sandbox` * `hiloop.api.sandbox_service.sandbox_service_list_sandbox_snapshots` * `hiloop.api.sandbox_service.sandbox_service_list_sandboxes` * `hiloop.api.sandbox_service.sandbox_service_update_sandbox` ### Volumes * `hiloop.api.volume_service.volume_service_create_volume` * `hiloop.api.volume_service.volume_service_delete_volume` * `hiloop.api.volume_service.volume_service_get_volume` * `hiloop.api.volume_service.volume_service_list_volumes` * `hiloop.api.volume_service.volume_service_publish_volume_version` * `hiloop.api.volume_service.volume_service_request_volume_blob_uploads` * `hiloop.api.volume_service.volume_service_start_volume_push` ### Saved & data views * `hiloop.api.telemetry_view_service.telemetry_view_service_delete_data_view` * `hiloop.api.telemetry_view_service.telemetry_view_service_list_data_views` * `hiloop.api.telemetry_view_service.telemetry_view_service_put_data_view` * `hiloop.api.telemetry_view_service.telemetry_view_service_run_data_view` ### Annotations * `hiloop.api.annotation_service.annotation_service_annotate` * `hiloop.api.annotation_service.annotation_service_annotate_range` * `hiloop.api.annotation_service.annotation_service_list_annotations` ### Annotation schemas * `hiloop.api.annotation_schema_service.annotation_schema_service_archive_annotation_schema` * `hiloop.api.annotation_schema_service.annotation_schema_service_get_annotation_schema` * `hiloop.api.annotation_schema_service.annotation_schema_service_list_annotation_schemas` * `hiloop.api.annotation_schema_service.annotation_schema_service_register_annotation_schema` ### Runs * `hiloop.api.run_service.run_service_complete_run` * `hiloop.api.run_service.run_service_get_run` * `hiloop.api.run_service.run_service_list_runs` * `hiloop.api.run_service.run_service_start_run` ### Secrets * `hiloop.api.secret_service.secret_service_create_sandbox_secret` * `hiloop.api.secret_service.secret_service_grant_sandbox_secret` * `hiloop.api.secret_service.secret_service_list_sandbox_secret_grants` * `hiloop.api.secret_service.secret_service_list_sandbox_secrets` * `hiloop.api.secret_service.secret_service_revoke_sandbox_secret` * `hiloop.api.secret_service.secret_service_rotate_sandbox_secret` * `hiloop.api.secret_service.secret_service_ungrant_sandbox_secret` ### Workloads * `hiloop.api.workload_service.workload_service_add_workload_federation` * `hiloop.api.workload_service.workload_service_create_workload` * `hiloop.api.workload_service.workload_service_delete_workload` * `hiloop.api.workload_service.workload_service_get_workload` * `hiloop.api.workload_service.workload_service_list_workload_federation` * `hiloop.api.workload_service.workload_service_list_workloads` * `hiloop.api.workload_service.workload_service_remove_workload_federation` * `hiloop.api.workload_service.workload_service_set_workload_launch_acl` ### Usage * `hiloop.api.usage_service.usage_service_get_usage_snapshot` ### Projects * `hiloop.api.project_service.project_service_create_project` * `hiloop.api.project_service.project_service_delete_project` * `hiloop.api.project_service.project_service_get_project` * `hiloop.api.project_service.project_service_list_projects` * `hiloop.api.project_service.project_service_update_project` ### Discovery * `hiloop.api.meta_service.meta_service_get_service_config` ### Identity * `hiloop.api.identity_service.identity_service_who_am_i` ### Feedback * `hiloop.api.feedback_service.feedback_service_create_feedback` ## Models Contains all the data models used in inputs/outputs ### AddWorkloadFederationRequest ```python theme={null} @_attrs_define class AddWorkloadFederationRequest() ``` **Attributes**: * `name` *str | Unset* - The registered workload name. * `cloud` *str | Unset* - Cloud provider: aws, gcp, or azure. * `descriptor` *WorkloadFederationDescriptor | Unset* - Cloud-specific parameters for one workload federation registration. Only the fields belonging to the selected cloud may be set. AWS requires role\_arn and defaults an empty region to us-east-1. Google Cloud requires project\_id, project\_number, pool\_id, and provider\_id; service\_account\_email is optional. Microsoft Entra requires application\_id and entra\_tenant\_id. ### AddWorkloadFederationResponse ```python theme={null} @_attrs_define class AddWorkloadFederationResponse() ``` **Attributes**: * `federation_config` *WorkloadFederationConfig | Unset* - One live cloud-federation registration owned by a workload. The audience is provider-canonical and server-derived from cloud and descriptor; it is the exact value the workload may request from the workload-identity issuer. ### AnnotateRangeRequest ```python theme={null} @_attrs_define class AnnotateRangeRequest() ``` A range annotation spanning a window within a run (rather than a single target event). The window is either a pair of wall-clock nanosecond bounds or a pair of event ids whose recorded timestamps become the bounds — supply exactly one form. **Attributes**: * `run_id` *str | Unset* - The run (session) the annotation belongs to. * `schema_name` *str | Unset* - The registered annotation-schema name the payload validates against (the event `name`). * `range_start_ns` *str | Unset* - Inclusive start of the annotated window, in wall-clock nanoseconds. Mutually exclusive with the event-pair form. * `range_end_ns` *str | Unset* - Inclusive end of the annotated window, in wall-clock nanoseconds. Mutually exclusive with the event-pair form. * `payload_json` *str | Unset* - The annotation payload as a JSON object string; validated against `schema_name`'s registered JSON Schema at ingest. Reserved `hiloop.annotation.*` keys are platform-owned and excluded. * `range_start_event_id` *str | Unset* - The `event_id` whose recorded timestamp starts the annotated window. Both event endpoints must exist in `run_id`; the window bounds are materialized from their timestamps. Set together with `range_end_event_id`, and not alongside the nanosecond bounds. * `range_end_event_id` *str | Unset* - The `event_id` whose recorded timestamp ends the annotated window. Set together with `range_start_event_id`, and not alongside the nanosecond bounds. * `event_id` *str | Unset* - Optional caller-minted `event_id` for the annotation event (a 26-character ULID). Supplying one makes retries safe: re-sending the request with the same `event_id` returns the existing annotation instead of writing a duplicate, so an ambiguous failure (a 5xx or a lost response) can be retried blindly. The id names this logical annotation — never reuse it for different content. Omitted, the server mints a fresh id per call and a retry writes a new annotation. ### AnnotateRequest ```python theme={null} @_attrs_define class AnnotateRequest() ``` One annotation: run-scoped (optionally targeting a single event within the run) or project-scoped (no run — durable cross-run knowledge that outlives any sandbox). **Attributes**: * `run_id` *str | Unset* - The run (session) the annotation belongs to. Exactly one of `run_id` or `project_id` is set. * `schema_name` *str | Unset* - The registered annotation-schema name the payload validates against (the event `name`). * `target_event_id` *str | Unset* - The `event_id` of the single event this annotation is about. Only valid with `run_id`; empty annotates the run (or project) itself. * `payload_json` *str | Unset* - The annotation payload as a JSON object string; validated against `schema_name`'s registered JSON Schema at ingest. Reserved `hiloop.annotation.*` keys are platform-owned and excluded. * `project_id` *str | Unset* - The project a run-less annotation belongs to. Exactly one of `run_id` or `project_id` is set; a project-scoped annotation carries no run lineage and no target event. * `event_id` *str | Unset* - Optional caller-minted `event_id` for the annotation event (a 26-character ULID). Supplying one makes retries safe: re-sending the request with the same `event_id` returns the existing annotation instead of writing a duplicate, so an ambiguous failure (a 5xx or a lost response) can be retried blindly. The id names this logical annotation — never reuse it for different content. Omitted, the server mints a fresh id per call and a retry writes a new annotation. ### AnnotateResponse ```python theme={null} @_attrs_define class AnnotateResponse() ``` **Attributes**: * `event_id` *str | Unset* - The stable `event_id` of the annotation event (the dedup/lookup key): the caller-minted id when the request carried one, otherwise the freshly server-minted one. ### AnnotationSchema ```python theme={null} @_attrs_define class AnnotationSchema() ``` One registered annotation-schema config: a single immutable, versioned row of the registry. **Attributes**: * `id` *str | Unset* - The config id. * `name` *str | Unset* - The schema name — unique per org across versions (the registered name an annotation names). * `version` *str | Unset* - The monotonic version within (org, name). The first registration is 1. * `description` *str | Unset* - An optional human-readable description. * `json_schema` *str | Unset* - The JSON Schema document (draft 2020-12) as a JSON string. * `archived_at` *str | Unset* - When the config was archived (RFC 3339), or empty if it is still live. * `created_at` *str | Unset* - When the config version was created (RFC 3339). * `promoted_fields` *list\[PromotedField] | Unset* - The fields this schema promotes from the payload into typed columns, each with its server-assigned slot. Empty when the schema promotes nothing. ### ArchiveAnnotationSchemaRequest ```python theme={null} @_attrs_define class ArchiveAnnotationSchemaRequest() ``` **Attributes**: * `name` *str | Unset* - The schema name to archive. * `version` *str | Unset* - The specific version to archive. 0 (or omitted) means the latest live version. ### ArchiveAnnotationSchemaResponse ```python theme={null} @_attrs_define class ArchiveAnnotationSchemaResponse() ``` **Attributes**: * `schema` *AnnotationSchema | Unset* - One registered annotation-schema config: a single immutable, versioned row of the registry. ### CompleteRunRequest ```python theme={null} @_attrs_define class CompleteRunRequest() ``` **Attributes**: * `id` *str | Unset* - The run to complete. * `status` *str | Unset* - The terminal status to record: succeeded, failed, or canceled. ### CompleteRunResponse ```python theme={null} @_attrs_define class CompleteRunResponse() ``` **Attributes**: * `run` *Run | Unset* - A run record (the subset the API returns). Intentionally carries no cost or spend roll-up: the product is generic and does not surface cost by default. ### CreateFeedbackRequest ```python theme={null} @_attrs_define class CreateFeedbackRequest() ``` **Attributes**: * `title` *str | Unset* - A short summary of the report. Required; at most 300 characters. * `surface` *str | Unset* - The product surface the report is about. Required; one of `cli`, `api`, `web`, `sandbox`, `telemetry`, `annotations`, `docs`, or `other`. * `severity` *str | Unset* - How severe the problem is. Optional; one of `critical`, `high`, `medium`, or `low`. Leave it empty for general feedback that is not a bug. * `body` *str | Unset* - Free-form feedback text. Optional; at most 10,000 characters. * `expected` *str | Unset* - What was expected to happen. Optional; at most 10,000 characters. * `actual` *str | Unset* - What actually happened. Optional; at most 10,000 characters. * `repro` *str | Unset* - Steps to reproduce the problem. Optional; at most 10,000 characters. * `evidence` *list\[str] | Unset* - Correlation keys — run, event, or artifact ids — linking the report to recorded telemetry. Optional; at most 50 entries, each at most 256 characters. * `fingerprint` *str | Unset* - A stable, content-derived deduplication key (for example `<surface>/`). Enforced: a submission whose fingerprint already exists returns the original report's id instead of storing (and surfacing) a duplicate, which makes retrying a lost response safe. When omitted, the server derives one from the report's content, so re-sending an identical report also converges. Optional; at most 300 characters. * `hiloop_version` *str | Unset* - The hiloop client version that produced the report. Optional; at most 100 characters. ### CreateFeedbackResponse ```python theme={null} @_attrs_define class CreateFeedbackResponse() ``` **Attributes**: * `id` *str | Unset* - The stored report's id. * `relayed` *bool | Unset* - Whether the report was surfaced to the team's review channel. The report is stored either way, so a `false` here never means the feedback was lost. ### CreateProjectRequest ```python theme={null} @_attrs_define class CreateProjectRequest() ``` **Attributes**: * `slug` *str | Unset* - The project slug — unique within the caller's organization. * `name` *str | Unset* - The human-readable project name. * `description` *str | Unset* - An optional user-assigned free-text description (at most 4 KiB). Empty leaves the project undescribed. ### CreateProjectResponse ```python theme={null} @_attrs_define class CreateProjectResponse() ``` **Attributes**: * `project` *Project | Unset* - A project record (the subset the API returns). ### CreateSandboxFromImageRequest ```python theme={null} @_attrs_define class CreateSandboxFromImageRequest() ``` Create a root sandbox from an OCI image; omitting image starts from the platform default image. **Attributes**: * `image` *str | Unset* - The unmodified OCI image reference to start from. * `ttl_seconds` *int | Unset* - Sandbox lifetime in seconds. Omit it to use the deployment default. * `storage_class` *CreateSandboxFromImageRequestStorageClass | Unset* - Storage behavior for the sandbox. Omit it to use durable storage when restoring a snapshot, or standard storage for an image/platform-default create. Default: CreateSandboxFromImageRequestStorageClass.STANDARD. * `ports` *list\[int] | Unset* - Unique guest TCP ports in the range 1-65535. Returned endpoints are authenticated private session-plane connections, not public preview URLs. * `volumes` *list\[SandboxVolumeMount] | Unset* - Pre-registered volumes to mount, each pinned to its current version at admission. * `secrets` *list\[SandboxSecretBinding] | Unset* - Pre-registered secrets to bind for proof-bound request-time delivery. * `metadata` *CreateSandboxFromImageRequestMetadata | Unset* - Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. * `name` *str | Unset* - Optional customer-supplied name, unique among the project's sandboxes that have not finished deleting. It must be 1-63 characters: lowercase letters or digits, with interior hyphens allowed. Omit it to leave the sandbox unnamed; the server never generates a name. A duplicate returns 409 name\_conflict; a terminated sandbox's name is free to reuse, and its record keeps the name for history. * `resources` *ResourceSpec | Unset* - Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it. * `command` *list\[str] | Unset* - Argv that replaces the image's own entrypoint as the sandbox's first process. Omit it to run the image's ENTRYPOINT/CMD unchanged, which is what an image built to hold itself open wants. Supply it for an image whose entrypoint runs a task and exits, such as a base OS image or a build tool: a sandbox is something you attach to, and it lives only as long as its first process. The argv is executed directly rather than through a shell, so pipes and redirection belong inside a command you name explicitly. The executable must not be empty; at most 256 entries, each at most 4096 characters. * `workspace_capacity_gib` *int | Unset* - Durable workspace capacity in whole GiB. A root create may omit it to use the deployment default; a snapshot create inherits the snapshot-time value. A legacy snapshot whose capacity predates stamping requires an explicit value. This field is valid only with durable storage; standard storage has no persistent workspace claim. * `placement_class` *CreateSandboxFromImageRequestPlacementClass | Unset* - Capacity posture for this sandbox. Omit it to use standard placement. * `idle_timeout_seconds` *int | Unset* - Idle duration in seconds after which a running sandbox is stopped. Omit it to use the deployment default; when the deployment has no default, idle stopping is disabled. Values are from 60 through 86400. * `shared_filesystems` *list\[SandboxSharedFilesystemMount] | Unset* - Deployment-registered shared filesystems to mount. Shared filesystems are external to this sandbox's snapshots; durable storage is required for the sandbox's private runtime state. * `network_access` *CreateSandboxFromImageRequestNetworkAccess | Unset* - Outbound-network posture. Omit it to use public access. ### CreateSandboxFromImageRequestMetadata ```python theme={null} @_attrs_define class CreateSandboxFromImageRequestMetadata() ``` Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### CreateSandboxFromSnapshotRequest ```python theme={null} @_attrs_define class CreateSandboxFromSnapshotRequest() ``` Create a child sandbox from an existing snapshot. **Attributes**: * `snapshot_id` *str* - The snapshot to restore as a new child sandbox. * `ttl_seconds` *int | Unset* - Sandbox lifetime in seconds. Omit it to use the deployment default. * `storage_class` *CreateSandboxFromSnapshotRequestStorageClass | Unset* - Storage behavior for the sandbox. Omit it to use durable storage when restoring a snapshot, or standard storage for an image/platform-default create. Default: CreateSandboxFromSnapshotRequestStorageClass.DURABLE. * `ports` *list\[int] | Unset* - Unique guest TCP ports in the range 1-65535. Returned endpoints are authenticated private session-plane connections, not public preview URLs. * `volumes` *list\[SandboxVolumeMount] | Unset* - Pre-registered volumes to mount, each pinned to its current version at admission. * `secrets` *list\[SandboxSecretBinding] | Unset* - Pre-registered secrets to bind for proof-bound request-time delivery. * `image_override` *str | Unset* - The image to run the restored workspace on, when it should not be the one the snapshot recorded. Only meaningful with snapshot\_id: a snapshot carries workspace bytes, and this names the runtime they are materialized onto, which is how a sandbox takes a newer base image without losing what is in its workspace. Omit it to run the image the snapshot recorded. * `metadata` *CreateSandboxFromSnapshotRequestMetadata | Unset* - Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. * `name` *str | Unset* - Optional customer-supplied name, unique among the project's sandboxes that have not finished deleting. It must be 1-63 characters: lowercase letters or digits, with interior hyphens allowed. Omit it to leave the sandbox unnamed; the server never generates a name. A duplicate returns 409 name\_conflict; a terminated sandbox's name is free to reuse, and its record keeps the name for history. * `resources` *ResourceSpec | Unset* - Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it. * `command` *list\[str] | Unset* - Argv that replaces the image's own entrypoint as the sandbox's first process. Omit it to run the image's ENTRYPOINT/CMD unchanged, which is what an image built to hold itself open wants. Supply it for an image whose entrypoint runs a task and exits, such as a base OS image or a build tool: a sandbox is something you attach to, and it lives only as long as its first process. The argv is executed directly rather than through a shell, so pipes and redirection belong inside a command you name explicitly. The executable must not be empty; at most 256 entries, each at most 4096 characters. * `workspace_capacity_gib` *int | Unset* - Durable workspace capacity in whole GiB. A root create may omit it to use the deployment default; a snapshot create inherits the snapshot-time value. A legacy snapshot whose capacity predates stamping requires an explicit value. This field is valid only with durable storage; standard storage has no persistent workspace claim. * `placement_class` *CreateSandboxFromSnapshotRequestPlacementClass | Unset* - Capacity posture for this sandbox. Omit it to use standard placement. * `idle_timeout_seconds` *int | Unset* - Idle duration in seconds after which a running sandbox is stopped. Omit it to use the deployment default; when the deployment has no default, idle stopping is disabled. Values are from 60 through 86400. * `shared_filesystems` *list\[SandboxSharedFilesystemMount] | Unset* - Deployment-registered shared filesystems to mount. Shared filesystems are external to this sandbox's snapshots; durable storage is required for the sandbox's private runtime state. * `network_access` *CreateSandboxFromSnapshotRequestNetworkAccess | Unset* - Outbound-network posture. Omit it to use public access. ### CreateSandboxFromSnapshotRequestMetadata ```python theme={null} @_attrs_define class CreateSandboxFromSnapshotRequestMetadata() ``` Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### CreateSandboxResponse ```python theme={null} @_attrs_define class CreateSandboxResponse() ``` **Attributes**: * `id` *str* - The new sandbox id. Poll GetSandbox with this id for observed lifecycle state. * `request_state` *CreateSandboxResponseRequestState* - The accepted mutation-request state, distinct from observed sandbox lifecycle state. * `run_id` *str* - The ambient run that receives telemetry captured for this sandbox. An idempotent create retry returns the same run id. ### CreateSandboxSecretRequest ```python theme={null} @_attrs_define class CreateSandboxSecretRequest() ``` **Attributes**: * `name` *str | Unset* - The secret name — unique within the caller's organization. * `value` *str | Unset* - The secret value. WRITE-ONLY: stored encrypted for proof-bound delivery and never returned by these management APIs. * `dest_host` *str | Unset* - The exact public HTTPS destination. Must be a bare DNS hostname such as `api.openai.com`, not a URL or IP address; stored in canonical lowercase form. Must be empty for sandbox-environment delivery. * `delivery` *CreateSandboxSecretRequestDelivery | Unset* - The only trusted data plane allowed to release this secret. Defaults to generic secret egress. ### CreateSandboxSecretResponse ```python theme={null} @_attrs_define class CreateSandboxSecretResponse() ``` **Attributes**: * `secret` *SandboxSecret | Unset* - A sandbox-secret record — metadata only, never the value. ### CreateSandboxSnapshotBody ```python theme={null} @_attrs_define class CreateSandboxSnapshotBody() ``` **Attributes**: * `name` *str | Unset* - Optional human-readable snapshot name used by list filtering, from 1 through 128 characters. * `wait_remote` *bool | Unset* - When true, wait for confirmed remote replication before returning the receipt. When false, return after the local storage snapshot exists. The wait is bounded by wait\_timeout\_seconds. Default: False. * `wait_timeout_seconds` *int | Unset* - Remote-replication wait bound in seconds, from 1 through 25. At the deadline, return the same snapshot id with truthful local durability rather than holding the request longer. ### CreateSandboxSnapshotResponse ```python theme={null} @_attrs_define class CreateSandboxSnapshotResponse() ``` **Attributes**: * `snapshot_id` *str* - The new immutable snapshot id. * `durability` *CreateSandboxSnapshotResponseDurability* - Durability proven before this receipt was returned. ### CreateVolumeRequest ```python theme={null} @_attrs_define class CreateVolumeRequest() ``` **Attributes**: * `project_id` *str | Unset* - The project the volume belongs to. * `name` *str | Unset* - The volume name — unique within the project (letters, digits, dots, dashes, underscores; at most 100 characters). * `description` *str | Unset* - An optional user-assigned free-text description (at most 4 KiB). Empty leaves the volume undescribed. * `quota_bytes` *str | Unset* - Storage quota in bytes (required). A quota, not an allocation; at most 2 TiB per volume. ### CreateVolumeResponse ```python theme={null} @_attrs_define class CreateVolumeResponse() ``` **Attributes**: * `volume` *Volume | Unset* - A volume record (the subset the API returns). ### CreateWorkloadRequest ```python theme={null} @_attrs_define class CreateWorkloadRequest() ``` **Attributes**: * `name` *str | Unset* - The workload name to register — unique within the organization. Lowercase letters, digits, `.`, `_`, and `-`; must start and end with a letter or digit; at most 100 characters. * `description` *str | Unset* - A free-text description of what the workload is for. Optional. ### CreateWorkloadResponse ```python theme={null} @_attrs_define class CreateWorkloadResponse() ``` **Attributes**: * `workload` *Workload | Unset* - A registered workload identity, scoped to the caller's organization. ### DataView ```python theme={null} @_attrs_define class DataView() ``` A structured data view: a named, versioned spec that compiles 1:1 to a safe query. **Attributes**: * `name` *str | Unset* - The view name, unique within an organization among non-deleted views. * `description` *str | Unset* - A human description, surfaced in the console switcher. * `spec` *DataViewSpec | Unset* - The data-view spec as opaque JSON — the engine's tagged `DataViewSpec`: a raw `Sql` `SELECT`, plus opaque render config. Carried as a Struct so the spec schema lives in ONE place (the engine's serde types); the service never re-models it. Re-validated against the current column allowlist on store and on every run, so a view referencing a dropped column fails closed with INVALID\_ARGUMENT rather than serving a stale result. * `spec_version` *str | Unset* - Monotonic per-edit version; the store bumps it on each upsert. ### DataViewSpec ```python theme={null} @_attrs_define class DataViewSpec() ``` The data-view spec as opaque JSON — the engine's tagged `DataViewSpec`: a raw `Sql` `SELECT`, plus opaque render config. Carried as a Struct so the spec schema lives in ONE place (the engine's serde types); the service never re-models it. Re-validated against the current column allowlist on store and on every run, so a view referencing a dropped column fails closed with INVALID\_ARGUMENT rather than serving a stale result. ### DeleteDataViewResponse ```python theme={null} @_attrs_define class DeleteDataViewResponse() ``` ### DeleteProjectResponse ```python theme={null} @_attrs_define class DeleteProjectResponse() ``` The delete's effect report: how many of each dependent resource the call actually removed. All counts are zero for a non-cascading delete (it only ever removes a project with no dependents). **Attributes**: * `runs_deleted` *str | Unset* - The number of runs deleted. * `volumes_deleted` *str | Unset* - The number of volumes deleted. * `secrets_deleted` *str | Unset* - The number of project-scoped secrets deleted. * `api_keys_deleted` *str | Unset* - The number of project-scoped API keys deleted (keys scoped to the whole organization are untouched). ### DeleteSandboxResponse ```python theme={null} @_attrs_define class DeleteSandboxResponse() ``` **Attributes**: * `id` *str* - The sandbox id whose deletion was accepted. * `request_state` *DeleteSandboxResponseRequestState* - The accepted mutation-request state, distinct from observed sandbox lifecycle state. ### DeleteSandboxSnapshotResponse ```python theme={null} @_attrs_define class DeleteSandboxSnapshotResponse() ``` ### DeleteVolumeResponse ```python theme={null} @_attrs_define class DeleteVolumeResponse() ``` ### DeleteWorkloadResponse ```python theme={null} @_attrs_define class DeleteWorkloadResponse() ``` ### ErrorBody ```python theme={null} @_attrs_define class ErrorBody() ``` **Attributes**: * `code` *str* - Stable machine-readable error code in snake\_case. * `message` *str* - Human-readable description; clients must not parse it. details (ErrorDetails | Unset): * `request_id` *str | Unset* - Correlation id present on server faults. ### ErrorDetails ```python theme={null} @_attrs_define class ErrorDetails() ``` **Attributes**: quota (QuotaDetails | Unset): ### ExecSandboxBody ```python theme={null} @_attrs_define class ExecSandboxBody() ``` **Attributes**: * `cmd` *list\[str]* - Command and arguments. The first entry is a non-empty executable; at most 256 entries are accepted and each entry is at most 4096 characters. * `timeout_seconds` *int | Unset* - Execution timeout in whole seconds, from 1 through 3600. Omit it to use the server default; sub-second budgets are outside this version. * `secret_environment` *list\[SandboxExecSecretEnvironment] | Unset* - Secret references released atomically into the child environment. No value crosses this public API. Omit for ordinary execution. ### ExecSandboxCompletedResponse ```python theme={null} @_attrs_define class ExecSandboxCompletedResponse() ``` Buffered output and the real exit code from a completed command; truncated reports output loss independently. **Attributes**: * `stdout` *str* - Buffered standard output. It may contain partial output on a timeout or an indeterminate outcome. * `stderr` *str* - Buffered standard error. It may contain partial output on a timeout or an indeterminate outcome. * `exit_` *int* - The process exit code for a completed command, including zero. * `truncated` *bool* - Whether stdout or stderr was truncated at the server-configured combined output cap. The default cap is no more than 1 MiB. Truncation does not replace the real process outcome. ### ExecSandboxIndeterminateResponse ```python theme={null} @_attrs_define class ExecSandboxIndeterminateResponse() ``` The command was dispatched but its outcome could not be read, so no exit code is reported; any output collected first is still returned. It may have completed: do not re-run a command that is unsafe to repeat without checking, or send an Idempotency-Key so a retry replays instead of re-executing. **Attributes**: * `stdout` *str* - Buffered standard output. It may contain partial output on a timeout or an indeterminate outcome. * `stderr` *str* - Buffered standard error. It may contain partial output on a timeout or an indeterminate outcome. * `indeterminate` *SandboxExecIndeterminate* - Presence marker returned when the command was dispatched but its execution channel was lost before an outcome could be read, so the service cannot say what the command did. This is not a failure to run. The command may have run to completion, and any output collected before the channel was lost is still returned. Treat it as "unknown", never as "did not run": re-issuing a command that is not safe to run twice requires an Idempotency-Key, which replays the recorded outcome instead of executing again. * `truncated` *bool* - Whether stdout or stderr was truncated at the server-configured combined output cap. The default cap is no more than 1 MiB. Truncation does not replace the real process outcome. ### ExecSandboxTimedOutResponse ```python theme={null} @_attrs_define class ExecSandboxTimedOutResponse() ``` Partial buffered output from a timed-out command, with no exit code; truncated reports output loss independently. **Attributes**: * `stdout` *str* - Buffered standard output. It may contain partial output on a timeout or an indeterminate outcome. * `stderr` *str* - Buffered standard error. It may contain partial output on a timeout or an indeterminate outcome. * `timeout` *SandboxExecTimeout* - Presence marker returned when an execution exceeded its requested timeout. * `truncated` *bool* - Whether stdout or stderr was truncated at the server-configured combined output cap. The default cap is no more than 1 MiB. Truncation does not replace the real process outcome. ### GetAnnotationSchemaResponse ```python theme={null} @_attrs_define class GetAnnotationSchemaResponse() ``` **Attributes**: * `schema` *AnnotationSchema | Unset* - One registered annotation-schema config: a single immutable, versioned row of the registry. ### GetProjectResponse ```python theme={null} @_attrs_define class GetProjectResponse() ``` **Attributes**: * `project` *Project | Unset* - A project record (the subset the API returns). ### GetRunResponse ```python theme={null} @_attrs_define class GetRunResponse() ``` **Attributes**: * `run` *Run | Unset* - A run record (the subset the API returns). Intentionally carries no cost or spend roll-up: the product is generic and does not surface cost by default. ### GetSandboxResponse ```python theme={null} @_attrs_define class GetSandboxResponse() ``` **Attributes**: * `sandbox` *SandboxFromImage | SandboxFromSnapshot* - One organization-scoped sandbox and its observed state. ### GetServiceConfigResponse ```python theme={null} @_attrs_define class GetServiceConfigResponse() ``` **Attributes**: * `telemetry_endpoint` *str | Unset* - Client-visible telemetry gRPC endpoint. * `login_url` *str | Unset* - API URL used to start the browser login flow. ### GetUsageSnapshotResponse ```python theme={null} @_attrs_define class GetUsageSnapshotResponse() ``` **Attributes**: * `snapshot` *UsageSnapshot | Unset* - Point-in-time quota usage for the caller's org. ### GetVolumeResponse ```python theme={null} @_attrs_define class GetVolumeResponse() ``` **Attributes**: * `volume` *Volume | Unset* - A volume record (the subset the API returns). ### GetWorkloadResponse ```python theme={null} @_attrs_define class GetWorkloadResponse() ``` **Attributes**: * `workload` *Workload | Unset* - A registered workload identity, scoped to the caller's organization. ### GrantSandboxSecretRequest ```python theme={null} @_attrs_define class GrantSandboxSecretRequest() ``` **Attributes**: * `id` *str | Unset* - The secret id to grant. * `subject_kind` *GrantSandboxSecretRequestSubjectKind | Unset* - The principal kind. * `subject_id` *str | Unset* - The principal's immutable id within subject\_kind. ### GrantSandboxSecretResponse ```python theme={null} @_attrs_define class GrantSandboxSecretResponse() ``` **Attributes**: * `grant` *SandboxSecretGrant | Unset* - One exact principal allowed to use one secret. Secret metadata visibility does not imply this authority. ### ListAnnotationSchemasResponse ```python theme={null} @_attrs_define class ListAnnotationSchemasResponse() ``` **Attributes**: * `schemas` *list\[AnnotationSchema] | Unset* - The configs in the caller's organization. By default the latest live version per name; with include\_archived, every version, newest first. ### ListAnnotationsResponse ```python theme={null} @_attrs_define class ListAnnotationsResponse() ``` **Attributes**: * `annotations` *list\[ListAnnotationsResponseAnnotationsItem] | Unset* - One annotation per row, newest first. Each row carries the annotation's identity and anchor (`event_id`, `run_id` — absent on project-scoped rows — `project_id`, `lineage_path`, the schema `name`, `ts_wall_ns`, `principal`), its target (`target_event_id`, or the range bounds `range_start_ns`/`range_end_ns` plus `range_start_event_id`/`range_end_event_id` when the range was event-bounded), and the schema-validated payload as a raw JSON object string under `payload_json` — the exact bytes that were annotated (the write-side `payload_json`), so payload values of every JSON type, including 64-bit integers, read back unchanged. Row fields are encoded canonically: snake\_case keys, 64-bit integers as decimal strings, absent fields omitted. * `skipped` *list\[SkippedAnnotation] | Unset* - Stored rows this listing could not decode (a legacy or corrupt storage shape), one entry per skipped row. The readable annotations above still serve in full; a listing that omits rows says so here rather than failing outright or dropping them silently. Empty on a healthy store. * `superseded_count` *str | Unset* - How many stored versions the default latest-wins view hid because a newer write shares their supersession key. Zero when nothing was superseded, and always zero with `history` (which returns every version). A non-zero count means acked writes are stored but not shown here — list with `history` to read them all. ### ListAnnotationsResponseAnnotationsItem ```python theme={null} @_attrs_define class ListAnnotationsResponseAnnotationsItem() ``` ### ListDataViewsResponse ```python theme={null} @_attrs_define class ListDataViewsResponse() ``` **Attributes**: * `views` *list\[DataView] | Unset* - The organization's structured data views. ### ListProjectsResponse ```python theme={null} @_attrs_define class ListProjectsResponse() ``` **Attributes**: * `projects` *list\[Project] | Unset* - The projects on this page, newest first. * `next_page_token` *str | Unset* - The token to pass as page\_token to fetch the next page. Empty when there are no more results. ### ListRunsResponse ```python theme={null} @_attrs_define class ListRunsResponse() ``` **Attributes**: * `runs` *list\[Run] | Unset* - The runs on this page, newest first. * `next_page_token` *str | Unset* - The token to pass as page\_token to fetch the next page. Empty when there are no more results. ### ListSandboxSecretGrantsResponse ```python theme={null} @_attrs_define class ListSandboxSecretGrantsResponse() ``` **Attributes**: * `grants` *list\[SandboxSecretGrant] | Unset* - At most 200 exact grants, sorted by kind and immutable id. ### ListSandboxSecretsResponse ```python theme={null} @_attrs_define class ListSandboxSecretsResponse() ``` **Attributes**: * `secrets` *list\[SandboxSecret] | Unset* - The secrets on this page, newest first — metadata only, never the value. * `next_page_token` *str | Unset* - The token to pass as page\_token to fetch the next page. Empty when there are no more results. ### ListSandboxSnapshotsResponse ```python theme={null} @_attrs_define class ListSandboxSnapshotsResponse() ``` **Attributes**: * `snapshots` *list\[SandboxSnapshot]* - The snapshots on this page, ordered by created\_at descending then id descending, including their parent lineage edges. * `next_page_token` *str* - Token for the next page. Empty means this is the final page. ### ListSandboxesResponse ```python theme={null} @_attrs_define class ListSandboxesResponse() ``` **Attributes**: * `sandboxes` *list\[SandboxFromImage | SandboxFromSnapshot]* - The sandboxes on this page, ordered by created\_at descending then id descending. * `next_page_token` *str* - Token for the next page. Empty means this is the final page. ### ListVolumesResponse ```python theme={null} @_attrs_define class ListVolumesResponse() ``` **Attributes**: * `volumes` *list\[Volume] | Unset* - The volumes on this page, newest first. * `next_page_token` *str | Unset* - The token to pass as page\_token to fetch the next page. Empty when there are no more results. ### ListWorkloadFederationResponse ```python theme={null} @_attrs_define class ListWorkloadFederationResponse() ``` **Attributes**: * `federation_configs` *list\[WorkloadFederationConfig] | Unset* - The workload's live registrations, in creation order. ### ListWorkloadsResponse ```python theme={null} @_attrs_define class ListWorkloadsResponse() ``` **Attributes**: * `workloads` *list\[Workload] | Unset* - The organization's registered workloads, by name. ### MetadataReplacement ```python theme={null} @_attrs_define class MetadataReplacement() ``` A presence-bearing complete replacement for caller-owned metadata. **Attributes**: * `entries` *MetadataReplacementEntries | Unset* - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### MetadataReplacementEntries ```python theme={null} @_attrs_define class MetadataReplacementEntries() ``` Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### OrgRef ```python theme={null} @_attrs_define class OrgRef() ``` The organization the caller acts in. **Attributes**: * `id` *str | Unset* - The organization id. * `slug` *str | Unset* - The organization slug. ### Principal ```python theme={null} @_attrs_define class Principal() ``` The acting principal, as resolved from the caller's credential by the API edge. The API trusts the edge-resolved identity; it does not re-authenticate. **Attributes**: * `kind` *str | Unset* - The kind of principal: "user" (a human identity), "service\_account" (a machine credential not bound to a user), or "workload" (a credential bound to a registered workload identity). * `id` *str | Unset* - The principal's stable id: the user's id for a user, the API key's id for a service account or a workload. * `email` *str | Unset* - The user's primary email. Empty for a service-account or workload principal. * `key_id` *str | Unset* - The presented API key's id. Empty for a browser-session login (no key is involved). * `key_name` *str | Unset* - The presented API key's name — how this principal is displayed in listings and attribution. Empty for a browser-session login. * `workload_name` *str | Unset* - The bound workload's registered name — how a workload principal is displayed in listings and attribution. Empty unless the presented credential is bound to a registered workload. ### Project ```python theme={null} @_attrs_define class Project() ``` A project record (the subset the API returns). **Attributes**: * `id` *str | Unset* - The project id. * `slug` *str | Unset* - The project slug — unique within the org. * `name` *str | Unset* - The human-readable project name. * `created_at` *str | Unset* - When the project was created (RFC 3339). * `version` *str | Unset* - Optimistic-concurrency version, bumped on every update. Echo it back as the `If-Match` request header to make a later update conditional — if the project changed meanwhile the server rejects the update with error code `precondition_failed` instead of overwriting. * `run_count` *str | Unset* - The total number of runs in the project, computed server-side across all of the project's runs (not just one page). * `last_run_at` *str | Unset* - When the most recent run in the project was created (RFC 3339), or empty when the project has no runs yet. * `description` *str | Unset* - User-assigned free-text description (at most 4 KiB). Empty when unset. * `created_by` *str | Unset* - Stable id of the principal that created the project — the API key (or user) that performed the create, recorded server-side, never client-supplied. Resolve it to a display name via the principals listing. Empty for projects created before attribution was recorded. * `updated_at` *str | Unset* - When the project was last updated (RFC 3339). Equal to created\_at until the first update. ### PromotedField ```python theme={null} @_attrs_define class PromotedField() ``` One org-declared field promoted from the annotation payload into a typed column for filter/sort/join speed. Unpromoted fields stay queryable from the JSON payload. The set of promoted fields is part of the immutable schema version, and slot bindings are stable across versions: a field keeps its slot in every later version (its type is permanent), a newly promoted field takes a never-used slot, and a slot is never re-bound to a different field, so rows written under any version stay readable by field name. **Attributes**: * `field` *str | Unset* - The payload field name to promote (e.g. "score"). Must be a field the schema's payload carries. * `type_` *PromotedFieldType | Unset* - The storage type to lift the field into. * `identity` *bool | Unset* - Whether this field is part of the latest-wins supersession identity. The default supersession key is the annotated target plus the schema name; declaring identity fields refines it (e.g. mark an "annotator" field identity to keep the latest write per annotator). Identity fields must be promoted, since dedup partitions on the typed column. * `bloom` *bool | Unset* - Request a point-lookup bloom filter for this field (str only; default false). Useful for a high-cardinality promoted id queried by exact match. * `slot` *str | Unset* - The server-assigned physical column the field binds to (read-only; ignored on a register request, populated on the stored/returned schema). ### PublishVolumeVersionRequest ```python theme={null} @_attrs_define class PublishVolumeVersionRequest() ``` **Attributes**: * `volume_id` *str | Unset* - The volume to publish the version on. * `push_id` *str | Unset* - The push handle from StartVolumePush, naming the uploaded manifest. ### PublishVolumeVersionResponse ```python theme={null} @_attrs_define class PublishVolumeVersionResponse() ``` **Attributes**: * `version` *VolumeVersion | Unset* - One immutable, committed volume version. The digest of the version's manifest (the canonical file listing) is the version's identity: identical content under the same parent always yields the same digest, and a version can never change after it is published. ### PutDataViewRequest ```python theme={null} @_attrs_define class PutDataViewRequest() ``` Create or replace a data view by name (upsert). The path `{name}` is authoritative; a `name` inside the body is ignored. **Attributes**: * `name` *str | Unset* - The view name (unique within the organization); supplied by the path. * `description` *str | Unset* - An optional human description. * `spec` *PutDataViewRequestSpec | Unset* - The data-view spec (opaque JSON, the engine's tagged `DataViewSpec`). Compile-validated before store. ### PutDataViewRequestSpec ```python theme={null} @_attrs_define class PutDataViewRequestSpec() ``` The data-view spec (opaque JSON, the engine's tagged `DataViewSpec`). Compile-validated before store. ### QueryResponse ```python theme={null} @_attrs_define class QueryResponse() ``` **Attributes**: * `rows` *list\[QueryResponseRowsItem] | Unset* - One flat JSON object per result row: column name -> bare scalar value, nulls omitted, 64-bit integers as decimal strings. For aggregate surfaces the columns are the grouping columns plus one per aggregate metric (e.g. "sum\_input\_tokens"). Reused by the view service. * `columns` *list\[str] | Unset* - The result set's declared column names, in projection order. Present even when a column is NULL in every row (per-row nulls are omitted), so a selected-but-empty column stays visible. ### QueryResponseRowsItem ```python theme={null} @_attrs_define class QueryResponseRowsItem() ``` ### QuotaDetails ```python theme={null} @_attrs_define class QuotaDetails() ``` **Attributes**: metric (str): limit (int): current (int | Unset): reserved (int | Unset): retry\_after\_seconds (int | Unset): ### QuotaLimit ```python theme={null} @_attrs_define class QuotaLimit() ``` One org quota limit and its current occupancy, when occupancy is meaningful. **Attributes**: * `metric` *str | Unset* - Stable metric name used by quota errors and usage displays. * `limit` *str | Unset* - Configured cap for the caller's organization. * `current` *str | Unset* - Current usage. Omitted for rate limits. ### RegisterAnnotationSchemaRequest ```python theme={null} @_attrs_define class RegisterAnnotationSchemaRequest() ``` **Attributes**: * `name` *str | Unset* - The schema name — unique per organization across versions. A new registration of an existing name creates the next version; an unseen name starts at version 1. * `json_schema` *str | Unset* - The JSON Schema document (draft 2020-12) as a JSON string. Must be a JSON object. * `description` *str | Unset* - An optional human-readable description for this version. * `promoted_fields` *list\[PromotedField] | Unset* - The payload fields to promote into typed columns for this version. The caller sets field/type/identity/bloom; the server assigns each field's slot, keeping a previously promoted field's slot and type. Registration is rejected if a field re-declares a different type, or if the schema has bound more fields of a type, across all its versions, than the slot pool holds. ### RegisterAnnotationSchemaResponse ```python theme={null} @_attrs_define class RegisterAnnotationSchemaResponse() ``` **Attributes**: * `schema` *AnnotationSchema | Unset* - One registered annotation-schema config: a single immutable, versioned row of the registry. ### RemoveWorkloadFederationResponse ```python theme={null} @_attrs_define class RemoveWorkloadFederationResponse() ``` ### RequestVolumeBlobUploadsRequest ```python theme={null} @_attrs_define class RequestVolumeBlobUploadsRequest() ``` **Attributes**: * `volume_id` *str | Unset* - The volume the blobs are being pushed for. * `blobs` *list\[VolumeBlobRef] | Unset* - The blobs to upload, at most 512 per request. Repeat the call in batches for larger pushes; it is read-only on the volume itself, so batches may run concurrently. ### RequestVolumeBlobUploadsResponse ```python theme={null} @_attrs_define class RequestVolumeBlobUploadsResponse() ``` **Attributes**: * `uploads` *list\[VolumeBlobUpload] | Unset* - One entry per distinct requested digest: either already present, or an upload URL. * `expires_in_seconds` *int | Unset* - How long the returned upload URLs stay valid, in seconds. ### ResourceSpec ```python theme={null} @_attrs_define class ResourceSpec() ``` Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it. **Attributes**: * `memory_mb` *int | Unset* - Requested memory in MB (mebibytes: 1024 MB = 1 GiB), from 1 through 1048576. Omit it to use the deployment default. * `gpus` *ResourceSpecGpus | Unset* - Requested accelerators. * `cpu_millis` *int | Unset* - Requested CPU in milliCPU, from 50 through 128000. 1000 milliCPU is one vCPU. Omit it to use the deployment default. ### ResourceSpecGpus ```python theme={null} @_attrs_define class ResourceSpecGpus() ``` Requested accelerators. **Attributes**: * `count` *int | Unset* - Integral accelerator count. * `models` *list\[str] | Unset* - Ordered fallback list of acceptable accelerator models. An empty list accepts any advertised model. ### RevokeSandboxSecretResponse ```python theme={null} @_attrs_define class RevokeSandboxSecretResponse() ``` **Attributes**: * `secret` *SandboxSecret | Unset* - A sandbox-secret record — metadata only, never the value. ### RotateSandboxSecretRequest ```python theme={null} @_attrs_define class RotateSandboxSecretRequest() ``` **Attributes**: * `id` *str | Unset* - The secret id to rotate. * `value` *str | Unset* - The new secret value. WRITE-ONLY: stored encrypted as a new version and never returned. ### RotateSandboxSecretResponse ```python theme={null} @_attrs_define class RotateSandboxSecretResponse() ``` **Attributes**: * `secret` *SandboxSecret | Unset* - A sandbox-secret record — metadata only, never the value. ### Run ```python theme={null} @_attrs_define class Run() ``` A run record (the subset the API returns). Intentionally carries no cost or spend roll-up: the product is generic and does not surface cost by default. **Attributes**: * `id` *str | Unset* - The run id (a client-supplied ULID, shared with telemetry). * `project_id` *str | Unset* - The project the run belongs to. * `label` *str | Unset* - An optional human-readable label. * `status` *str | Unset* - The run lifecycle status: pending, running, succeeded, failed, or canceled. * `created_by` *str | Unset* - The stable id of the principal that created the run — the API key (or user) that performed the start, recorded server-side. Empty when unrecorded. * `started_at` *str | Unset* - When the run started executing (RFC 3339), empty if it has not started. * `ended_at` *str | Unset* - When the run finished (RFC 3339), empty if it is still in flight. * `created_at` *str | Unset* - When the run record was created (RFC 3339). * `parent_run_id` *str | Unset* - The run this run continued from. Empty for a tree root. * `root_run_id` *str | Unset* - The root of this run's tree (equal to id for a root). Lets the whole tree resolve in one indexed lookup. * `lineage_path` *str | Unset* - The materialized path of run ids from the root to this run, as a dotted label (e.g. "root\_ulid.child\_ulid"). Sorts in creation order and addresses the subtree by prefix. * `last_activity_at` *str | Unset* - When the run last showed a liveness signal (RFC 3339): the time of its most recent telemetry event, or started\_at for a run that has emitted no events yet. Derived at read time, and only for a `running` run. Empty for every other run, and empty when the signal is temporarily unavailable. * `stale` *bool | Unset* - True when last\_activity\_at is older than the staleness window (15 minutes): the run still reads `running` — no terminal state is ever recorded on the creator's behalf — but its creator has gone quiet, so readers should render it as `running (stale)`. Always false when last\_activity\_at is empty. * `executing_principal` *str | Unset* - The stable id of the identity this run executes AS: the registered workload's id when the launch declared one, otherwise the launcher's own principal id (matching created\_by). Empty on runs that predate executing-identity recording. * `executing_kind` *str | Unset* - The executing identity's kind: `user`, `service_account`, or `workload`. Empty on runs that predate executing-identity recording. ### SandboxActivity ```python theme={null} @_attrs_define class SandboxActivity() ``` 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. **Attributes**: * `at` *str | Unset* - 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` *SandboxActivitySource | Unset* - What produced it. ### SandboxEndpoint ```python theme={null} @_attrs_define class SandboxEndpoint() ``` A port endpoint assigned to a sandbox. **Attributes**: * `port` *int* - The guest TCP port exposed by this endpoint. * `url` *str* - The authenticated URL clients use to reach the port. ### SandboxErrorBody ```python theme={null} @_attrs_define class SandboxErrorBody() ``` **Attributes**: * `code` *str* - Stable machine-readable error code in snake\_case. * `message` *str* - Human-readable description; clients must not parse it. * `request_id` *str* - Correlation id for support and diagnostics. ### SandboxExecIndeterminate ```python theme={null} @_attrs_define class SandboxExecIndeterminate() ``` Presence marker returned when the command was dispatched but its execution channel was lost before an outcome could be read, so the service cannot say what the command did. This is not a failure to run. The command may have run to completion, and any output collected before the channel was lost is still returned. Treat it as "unknown", never as "did not run": re-issuing a command that is not safe to run twice requires an Idempotency-Key, which replays the recorded outcome instead of executing again. ### SandboxExecSecretEnvironment ```python theme={null} @_attrs_define class SandboxExecSecretEnvironment() ``` One write-only secret reference mapped to one environment variable for this execution. The secret value is resolved by the server and never appears in this request. **Attributes**: * `secret_name` *str | Unset* - Name of an active sandbox-environment secret in the caller's organization, at most 128 bytes. * `variable_name` *str | Unset* - POSIX environment variable name populated in the child process, at most 128 bytes. ### SandboxExecTimeout ```python theme={null} @_attrs_define class SandboxExecTimeout() ``` Presence marker returned when an execution exceeded its requested timeout. ### SandboxFromImage ```python theme={null} @_attrs_define class SandboxFromImage() ``` A root sandbox created from an OCI image. **Attributes**: * `id` *str* - The stable sandbox id. * `state` *SandboxFromImageState* - The current observed lifecycle state. * `image` *str* - The OCI image reference used by a root sandbox. * `storage_class` *SandboxFromImageStorageClass* - The backing storage behavior selected at creation. * `endpoints` *list\[SandboxEndpoint]* - Authenticated private session-plane port endpoints. Empty until an endpoint is available; these are not public preview URLs. * `lineage_path` *str* - 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` *SandboxFromImageMetadata* - Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. * `created_at` *datetime.datetime* - When the sandbox was accepted, in RFC 3339 form. * `updated_at` *datetime.datetime* - When the sandbox record last changed, in RFC 3339 form. * `volumes` *list\[SandboxPinnedVolume]* - Admitted volumes with the immutable version pinned for this sandbox. * `workload_image` *str* - 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. * `placement_class` *SandboxFromImagePlacementClass* - The immutable capacity posture selected at creation. * `expires_at` *datetime.datetime | Unset* - The expiry time in RFC 3339 form. Omitted when the sandbox has no expiry. * `ssh` *SandboxSshConnection | Unset* - SSH connection information for a ready or running sandbox. * `state_reason` *SandboxStateReason | Unset* - A stable reason attached to a failed or quarantined lifecycle state. * `name` *str | Unset* - Customer-supplied name, unique among the project's sandboxes that have not finished deleting. Omitted when no name was supplied at creation. * `resources` *ResourceSpec | Unset* - Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it. * `created_by` *str | Unset* - 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` *SandboxActivity | Unset* - 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. * `workspace_capacity_gib` *int | Unset* - Durable workspace capacity in whole GiB. Omitted for standard storage and records that predate capacity stamping. * `idle_timeout_seconds` *int | Unset* - The resolved idle-stop duration in seconds. Omitted when idle stopping is disabled. * `idle_deadline` *datetime.datetime | Unset* - 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. * `shared_filesystems` *list\[SandboxSharedFilesystemMount] | Unset* - 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. ### SandboxFromImageMetadata ```python theme={null} @_attrs_define class SandboxFromImageMetadata() ``` Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### SandboxFromSnapshot ```python theme={null} @_attrs_define class SandboxFromSnapshot() ``` A child sandbox created from a snapshot. **Attributes**: * `id` *str* - The stable sandbox id. * `state` *SandboxFromSnapshotState* - The current observed lifecycle state. * `snapshot_id` *str* - The parent snapshot restored by a child sandbox. * `storage_class` *SandboxFromSnapshotStorageClass* - The backing storage behavior selected at creation. * `endpoints` *list\[SandboxEndpoint]* - Authenticated private session-plane port endpoints. Empty until an endpoint is available; these are not public preview URLs. * `lineage_path` *str* - 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` *SandboxFromSnapshotMetadata* - Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. * `created_at` *datetime.datetime* - When the sandbox was accepted, in RFC 3339 form. * `updated_at` *datetime.datetime* - When the sandbox record last changed, in RFC 3339 form. * `volumes` *list\[SandboxPinnedVolume]* - Admitted volumes with the immutable version pinned for this sandbox. * `workload_image` *str* - 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. * `placement_class` *SandboxFromSnapshotPlacementClass* - The immutable capacity posture selected at creation. * `expires_at` *datetime.datetime | Unset* - The expiry time in RFC 3339 form. Omitted when the sandbox has no expiry. * `ssh` *SandboxSshConnection | Unset* - SSH connection information for a ready or running sandbox. * `state_reason` *SandboxStateReason | Unset* - A stable reason attached to a failed or quarantined lifecycle state. * `name` *str | Unset* - Customer-supplied name, unique among the project's sandboxes that have not finished deleting. Omitted when no name was supplied at creation. * `resources` *ResourceSpec | Unset* - Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it. * `created_by` *str | Unset* - 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` *SandboxActivity | Unset* - 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. * `workspace_capacity_gib` *int | Unset* - Durable workspace capacity in whole GiB. Omitted for standard storage and records that predate capacity stamping. * `idle_timeout_seconds` *int | Unset* - The resolved idle-stop duration in seconds. Omitted when idle stopping is disabled. * `idle_deadline` *datetime.datetime | Unset* - 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. * `shared_filesystems` *list\[SandboxSharedFilesystemMount] | Unset* - 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. ### SandboxFromSnapshotMetadata ```python theme={null} @_attrs_define class SandboxFromSnapshotMetadata() ``` Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### SandboxNetworkAccessReceipt ```python theme={null} @_attrs_define class SandboxNetworkAccessReceipt() ``` 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. **Attributes**: network\_access (SandboxNetworkAccessReceiptNetworkAccess | Unset): pod\_uid (str | Unset): pod\_resource\_version (str | Unset): policies (list\[SandboxNetworkPolicyObservation] | Unset): ### SandboxNetworkPolicyObservation ```python theme={null} @_attrs_define class SandboxNetworkPolicyObservation() ``` One policy-controller observation that the exact live pod is selected by an egress policy. **Attributes**: policy\_name (str | Unset): policy\_endpoint\_name (str | Unset): policy\_endpoint\_uid (str | Unset): policy\_endpoint\_resource\_version (str | Unset): ### SandboxPinnedVolume ```python theme={null} @_attrs_define class SandboxPinnedVolume() ``` A mounted volume as admitted on a sandbox, including the immutable pinned version. **Attributes**: * `volume_id` *str* - The mounted volume id. * `version` *str* - The immutable volume version pinned at admission. * `target_path` *str* - The absolute mount path inside the sandbox. * `name` *str | Unset* - The mounted volume's name as resolved at admission. Empty when the volume had no name. ### SandboxQuotaErrorBody ```python theme={null} @_attrs_define class SandboxQuotaErrorBody() ``` **Attributes**: * `code` *str* - Stable machine-readable error code in snake\_case. * `message` *str* - Human-readable description; clients must not parse it. * `request_id` *str* - Correlation id for support and diagnostics. * `metric` *str* - Stable name of the exhausted quota metric. * `limit` *int* - Configured limit for the caller's organization. * `retry_after_seconds` *int* - Seconds to wait before retrying. ### SandboxSecret ```python theme={null} @_attrs_define class SandboxSecret() ``` A sandbox-secret record — metadata only, never the value. **Attributes**: * `id` *str | Unset* - The secret id. * `name` *str | Unset* - The human-readable secret name — unique within the organization. The sandbox spec references it by name. * `dest_host` *str | Unset* - Exact public HTTPS host to which proof-bound delivery is bound. Empty for sandbox- environment delivery, which is bound to an authorized sandbox execution instead of a network destination. * `current_version` *str | Unset* - The current version number. Starts at 1 and increments on each rotation. * `created_at` *str | Unset* - When the secret was created (RFC 3339). * `rotated_at` *str | Unset* - When the secret was last rotated, if ever (RFC 3339). * `expires_at` *str | Unset* - When the secret expires, if an expiry is set (RFC 3339). * `revoked_at` *str | Unset* - When the secret was revoked, if it has been (RFC 3339). A revoked secret cannot be delivered. * `delivery` *SandboxSecretDelivery | Unset* - The only trusted data plane allowed to release this secret. ### SandboxSecretBinding ```python theme={null} @_attrs_define class SandboxSecretBinding() ``` A pre-registered secret bound when the sandbox is created. **Attributes**: * `name` *str* - The registered secret name. Admission binds its exact proof-bound destination and use grant. ### SandboxSecretGrant ```python theme={null} @_attrs_define class SandboxSecretGrant() ``` One exact principal allowed to use one secret. Secret metadata visibility does not imply this authority. **Attributes**: * `secret_id` *str | Unset* - The granted secret id. * `subject_kind` *SandboxSecretGrantSubjectKind | Unset* - The principal kind. * `subject_id` *str | Unset* - The principal's immutable id within subject\_kind. ### SandboxServiceListSandboxesMetadata ```python theme={null} @_attrs_define class SandboxServiceListSandboxesMetadata() ``` At most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### SandboxSharedFilesystemMount ```python theme={null} @_attrs_define class SandboxSharedFilesystemMount() ``` 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. **Attributes**: * `filesystem_id` *str | Unset* - Deployment-registered filesystem id. * `subdirectory` *str | Unset* - Existing relative directory within the filesystem to mount. The directory must already exist when the sandbox pod starts. * `target_path` *str | Unset* - 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. ### SandboxSnapshot ```python theme={null} @_attrs_define class SandboxSnapshot() ``` One immutable sandbox snapshot and its lineage edge. **Attributes**: * `id` *str* - The stable snapshot id. * `source_sandbox_id` *str* - The sandbox whose state this snapshot records. * `lineage_path` *str* - The source sandbox's immutable lineage\_path. A child created from this snapshot appends its id to this value, making snapshot parentage the derivation source for sandbox lineage. * `durability` *SandboxSnapshotDurability* - The strongest durability currently confirmed for this snapshot. * `created_at` *datetime.datetime* - When the snapshot was created, in RFC 3339 form. * `image` *str* - The workload image behind this snapshot's lineage: the root sandbox's OCI image reference, inherited by every child sandbox created from this snapshot. * `name` *str | Unset* - Optional human-readable name supplied when the snapshot was created. * `parent_snapshot_id` *str | Unset* - The snapshot from which the source sandbox was created. Omitted for an image- created root. ### SandboxSshConnection ```python theme={null} @_attrs_define class SandboxSshConnection() ``` SSH connection information for a ready or running sandbox. **Attributes**: * `host` *str* - The session-plane hostname. * `port` *int* - The session-plane TCP port. * `user` *str* - The SSH username assigned to the sandbox session. ### SandboxStateReason ```python theme={null} @_attrs_define class SandboxStateReason() ``` A stable reason attached to a failed or quarantined lifecycle state. **Attributes**: * `code` *str* - Stable machine-readable reason code in snake\_case. * `message` *str* - Human-readable detail; clients must not parse it. ### SandboxVolumeMount ```python theme={null} @_attrs_define class SandboxVolumeMount() ``` A pre-registered volume mounted when the sandbox is created. **Attributes**: * `volume_id` *str* - The volume id to mount. Its current immutable version is pinned at admission. * `target_path` *str* - The absolute path at which the volume is mounted inside the sandbox. ### SetWorkloadLaunchAclRequest ```python theme={null} @_attrs_define class SetWorkloadLaunchAclRequest() ``` **Attributes**: * `name` *str | Unset* - The registered workload name. * `acl` *WorkloadLaunchAcl | Unset* - A per-workload launch ACL: which principals may launch a run or sandbox as the workload. ### SetWorkloadLaunchAclResponse ```python theme={null} @_attrs_define class SetWorkloadLaunchAclResponse() ``` **Attributes**: * `workload` *Workload | Unset* - A registered workload identity, scoped to the caller's organization. ### SkippedAnnotation ```python theme={null} @_attrs_define class SkippedAnnotation() ``` A stored annotation row a listing skipped because it could not be decoded, with the row's stored event id and the decode failure. Skipped rows are surfaced, never silently dropped: the listing stays available while naming exactly what it could not serve. **Attributes**: * `event_id` *str | Unset* - The stored `event_id` of the row that failed to decode. * `reason` *str | Unset* - Why the row could not be decoded. ### StartRunRequest ```python theme={null} @_attrs_define class StartRunRequest() ``` **Attributes**: * `project_id` *str | Unset* - The project the new run belongs to. * `parent_run_id` *str | Unset* - Optional parent run to continue the tree from. Empty starts a new tree root. * `label` *str | Unset* - An optional human-readable label. * `execute_as_workload` *str | Unset* - Optional registered workload name to run as. When set, the run is attributed to that workload (the caller must hold launch rights on it and the name must be registered); when empty, the run executes as the caller's own identity. The executing identity is always declared here, never inferred from the command. ### StartRunResponse ```python theme={null} @_attrs_define class StartRunResponse() ``` **Attributes**: * `run` *Run | Unset* - A run record (the subset the API returns). Intentionally carries no cost or spend roll-up: the product is generic and does not surface cost by default. ### StartVolumePushRequest ```python theme={null} @_attrs_define class StartVolumePushRequest() ``` **Attributes**: * `volume_id` *str | Unset* - The volume to push a new version to. ### StartVolumePushResponse ```python theme={null} @_attrs_define class StartVolumePushResponse() ``` **Attributes**: * `push_id` *str | Unset* - The push handle. Pass it to PublishVolumeVersion once the manifest and all content blobs are uploaded. * `manifest_upload_url` *str | Unset* - Short-lived pre-authorized URL to PUT the manifest (the JSON file listing: per file its path, mode, size, content digest, and chunk list) to. The URL is bound to this push's staging location; the request needs no additional credentials. * `expires_in_seconds` *int | Unset* - How long the upload URL stays valid, in seconds. * `max_manifest_bytes` *str | Unset* - The largest manifest the server accepts for this push, in bytes. ### UngrantSandboxSecretResponse ```python theme={null} @_attrs_define class UngrantSandboxSecretResponse() ``` ### UpdateProjectRequest ```python theme={null} @_attrs_define class UpdateProjectRequest() ``` **Attributes**: * `id` *str | Unset* - The project id to update. * `name` *str | Unset* - The new human-readable name (the slug is immutable). Omitted leaves the name unchanged. * `description` *str | Unset* - The new free-text description (at most 4 KiB). An empty value clears it; omitted leaves it unchanged. ### UpdateProjectResponse ```python theme={null} @_attrs_define class UpdateProjectResponse() ``` **Attributes**: * `project` *Project | Unset* - A project record (the subset the API returns). ### UpdateSandboxIdleTimeoutRequest ```python theme={null} @_attrs_define class UpdateSandboxIdleTimeoutRequest() ``` A sandbox update that includes a new idle-stop duration. **Attributes**: * `idle_timeout_seconds` *int* - New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged. * `state` *UpdateSandboxIdleTimeoutRequestState | Unset* - New desired lifecycle state. Omit it to leave lifecycle state unchanged. * `ttl_seconds` *int | Unset* - New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid. * `metadata` *UpdateSandboxIdleTimeoutRequestMetadata | Unset* - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### UpdateSandboxIdleTimeoutRequestMetadata ```python theme={null} @_attrs_define class UpdateSandboxIdleTimeoutRequestMetadata() ``` Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### UpdateSandboxMetadataRequest ```python theme={null} @_attrs_define class UpdateSandboxMetadataRequest() ``` A sandbox update that includes a metadata replacement. **Attributes**: * `metadata` *UpdateSandboxMetadataRequestMetadata* - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. * `state` *UpdateSandboxMetadataRequestState | Unset* - New desired lifecycle state. Omit it to leave lifecycle state unchanged. * `ttl_seconds` *int | Unset* - New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid. * `idle_timeout_seconds` *int | Unset* - New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged. ### UpdateSandboxMetadataRequestMetadata ```python theme={null} @_attrs_define class UpdateSandboxMetadataRequestMetadata() ``` Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### UpdateSandboxNetworkAccessRequest ```python theme={null} @_attrs_define class UpdateSandboxNetworkAccessRequest() ``` A retryable sandbox update that selects one closed outbound-network profile. **Attributes**: * `network_access` *UpdateSandboxNetworkAccessRequestNetworkAccess* - 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. ### UpdateSandboxResponse ```python theme={null} @_attrs_define class UpdateSandboxResponse() ``` **Attributes**: * `id` *str* - The sandbox id whose update was accepted. * `request_state` *UpdateSandboxResponseRequestState* - The accepted mutation-request state, distinct from observed sandbox lifecycle state. * `network_access_receipt` *SandboxNetworkAccessReceipt | Unset* - 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. ### UpdateSandboxStateRequest ```python theme={null} @_attrs_define class UpdateSandboxStateRequest() ``` A sandbox update that includes a lifecycle transition. **Attributes**: * `state` *UpdateSandboxStateRequestState* - New desired lifecycle state. Omit it to leave lifecycle state unchanged. * `ttl_seconds` *int | Unset* - New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid. * `metadata` *UpdateSandboxStateRequestMetadata | Unset* - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. * `idle_timeout_seconds` *int | Unset* - New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged. ### UpdateSandboxStateRequestMetadata ```python theme={null} @_attrs_define class UpdateSandboxStateRequestMetadata() ``` Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### UpdateSandboxTtlRequest ```python theme={null} @_attrs_define class UpdateSandboxTtlRequest() ``` A sandbox update that includes a new lifetime. **Attributes**: * `ttl_seconds` *int* - New positive lifetime in seconds from the time of this update. Omit it to leave expiry unchanged; zero is invalid. * `state` *UpdateSandboxTtlRequestState | Unset* - New desired lifecycle state. Omit it to leave lifecycle state unchanged. * `metadata` *UpdateSandboxTtlRequestMetadata | Unset* - Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. * `idle_timeout_seconds` *int | Unset* - New idle-stop duration in seconds, from 60 through 86400. Omit it to leave the current value unchanged. ### UpdateSandboxTtlRequestMetadata ```python theme={null} @_attrs_define class UpdateSandboxTtlRequestMetadata() ``` Replacement metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. ### UpdateSandboxWorkspaceRequest ```python theme={null} @_attrs_define class UpdateSandboxWorkspaceRequest() ``` A grow-only durable workspace capacity update. **Attributes**: * `workspace_capacity_gib` *int* - New durable workspace capacity in whole GiB. It must be at least the current capacity; shrinking a workspace is unsupported. ### UsageSnapshot ```python theme={null} @_attrs_define class UsageSnapshot() ``` Point-in-time quota usage for the caller's org. **Attributes**: * `limits` *list\[QuotaLimit] | Unset* - Every configured product quota. ### Volume ```python theme={null} @_attrs_define class Volume() ``` A volume record (the subset the API returns). **Attributes**: * `id` *str | Unset* - The volume id. * `project_id` *str | Unset* - The project the volume belongs to. * `name` *str | Unset* - The volume name — unique within its project. Limited to letters, digits, dots, dashes, and underscores (at most 100 characters). * `description` *str | Unset* - User-assigned free-text description (at most 4 KiB). Empty when unset. * `quota_bytes` *str | Unset* - Storage quota in bytes: the cap on the volume's total committed size. A quota, not an allocation — an empty volume consumes no storage. * `current_version_digest` *str | Unset* - Digest of the volume's current (latest committed) version. Empty until the first push publishes a version. * `created_by` *str | Unset* - Stable id of the principal that created the volume — the API key (or user) that performed the create, recorded server-side. Resolve it to a display name via the principals listing. * `created_at` *str | Unset* - When the volume was created (RFC 3339). * `updated_at` *str | Unset* - When the volume record was last updated (RFC 3339). Equal to created\_at until the first update. * `used_bytes` *str | Unset* - Committed storage in bytes: the total size of the distinct content blobs referenced by the volume's versions. Content is stored deduplicated, so a blob shared by several versions counts once — this is what the volume's committed content occupies, not the sum of its versions' sizes. Zero for a volume with no committed versions. ### VolumeBlobRef ```python theme={null} @_attrs_define class VolumeBlobRef() ``` One content blob (a whole small file, or one chunk of a larger file) the client intends to upload, identified by its digest. **Attributes**: * `digest` *str | Unset* - The blob's content digest (`blake3:<hex>`). * `size_bytes` *str | Unset* - The blob's exact size in bytes. Verified against the stored object before a version referencing the blob can be published. ### VolumeBlobUpload ```python theme={null} @_attrs_define class VolumeBlobUpload() ``` The upload decision for one requested blob. **Attributes**: * `digest` *str | Unset* - The blob's content digest, echoed from the request. * `present` *bool | Unset* - True when the blob already exists in the volume store — skip the upload; content is deduplicated by digest. * `upload_url` *str | Unset* - Short-lived pre-authorized URL to PUT the blob's bytes to. Empty when `present` is true. The URL is bound to the blob's content-addressed location; the request needs no additional credentials. ### VolumeVersion ```python theme={null} @_attrs_define class VolumeVersion() ``` One immutable, committed volume version. The digest of the version's manifest (the canonical file listing) is the version's identity: identical content under the same parent always yields the same digest, and a version can never change after it is published. **Attributes**: * `volume_id` *str | Unset* - The volume this version belongs to. * `version_digest` *str | Unset* - The version's identity: the digest of its manifest (`blake3:<hex>`). * `parent_version_digest` *str | Unset* - The digest of the version this one was published on top of. Empty for a volume's first version. * `size_bytes` *str | Unset* - Total content size in bytes across all files in the version. * `file_count` *str | Unset* - Number of files in the version. * `created_by` *str | Unset* - Stable id of the principal that published the version, recorded server-side. * `created_at` *str | Unset* - When the version was published (RFC 3339). ### WhoAmIResponse ```python theme={null} @_attrs_define class WhoAmIResponse() ``` **Attributes**: * `principal` *Principal | Unset* - The acting principal, as resolved from the caller's credential by the API edge. The API trusts the edge-resolved identity; it does not re-authenticate. * `organization` *OrgRef | Unset* - The organization the caller acts in. ### Workload ```python theme={null} @_attrs_define class Workload() ``` A registered workload identity, scoped to the caller's organization. **Attributes**: * `id` *str | Unset* - The workload's stable id. * `name` *str | Unset* - The workload's registered name — unique within the organization, and how the workload is displayed in attribution everywhere. Lowercase letters, digits, `.`, `_`, and `-`; must start and end with a letter or digit; at most 100 characters. * `description` *str | Unset* - A free-text description of what the workload is for. May be empty. * `launch_acl` *WorkloadLaunchAcl | Unset* - A per-workload launch ACL: which principals may launch a run or sandbox as the workload. * `created_by` *str | Unset* - Stable id of the principal that registered the workload, when recorded. * `created_at` *str | Unset* - When the workload was registered (RFC 3339). * `updated_at` *str | Unset* - When the workload's registration or ACL was last changed (RFC 3339). * `federation_configs` *list\[WorkloadFederationConfig] | Unset* - Live cloud-federation registrations owned by this workload, in creation order. ### WorkloadFederationConfig ```python theme={null} @_attrs_define class WorkloadFederationConfig() ``` One live cloud-federation registration owned by a workload. The audience is provider-canonical and server-derived from cloud and descriptor; it is the exact value the workload may request from the workload-identity issuer. **Attributes**: * `id` *str | Unset* - Stable handle used by federation list, remove, and setup. * `workload_id` *str | Unset* - Stable id of the workload that owns this registration. * `cloud` *str | Unset* - Cloud provider: aws, gcp, or azure. * `audience` *str | Unset* - Exact provider audience admitted for this workload. * `descriptor` *WorkloadFederationDescriptor | Unset* - Cloud-specific parameters for one workload federation registration. Only the fields belonging to the selected cloud may be set. AWS requires role\_arn and defaults an empty region to us-east-1. Google Cloud requires project\_id, project\_number, pool\_id, and provider\_id; service\_account\_email is optional. Microsoft Entra requires application\_id and entra\_tenant\_id. * `created_by` *str | Unset* - Stable id of the principal that created the registration, when recorded. * `created_at` *str | Unset* - When the registration was created (RFC 3339). ### WorkloadFederationDescriptor ```python theme={null} @_attrs_define class WorkloadFederationDescriptor() ``` Cloud-specific parameters for one workload federation registration. Only the fields belonging to the selected cloud may be set. AWS requires role\_arn and defaults an empty region to us-east-1. Google Cloud requires project\_id, project\_number, pool\_id, and provider\_id; service\_account\_email is optional. Microsoft Entra requires application\_id and entra\_tenant\_id. **Attributes**: * `role_arn` *str | Unset* - AWS IAM role trusted by this workload. * `region` *str | Unset* - AWS region used by the generated SDK configuration. Defaults to us-east-1. * `project_id` *str | Unset* - Google Cloud project id. * `project_number` *str | Unset* - Google Cloud project number. * `pool_id` *str | Unset* - Google Cloud workload identity pool id. * `provider_id` *str | Unset* - Google Cloud workload identity provider id. * `service_account_email` *str | Unset* - Optional Google Cloud service account to impersonate. * `application_id` *str | Unset* - Microsoft Entra application (client) id. * `entra_tenant_id` *str | Unset* - Microsoft Entra tenant id. ### WorkloadLaunchAcl ```python theme={null} @_attrs_define class WorkloadLaunchAcl() ``` A per-workload launch ACL: which principals may launch a run or sandbox as the workload. **Attributes**: * `policy` *WorkloadLaunchAclPolicy | Unset* - The launch policy: open to all org members, or restricted to the listed launchers. * `launchers` *list\[WorkloadLauncher] | Unset* - The principals allowed to launch as this workload. Meaningful only when the policy is WORKLOAD\_LAUNCH\_POLICY\_RESTRICTED; empty otherwise. ### WorkloadLauncher ```python theme={null} @_attrs_define class WorkloadLauncher() ``` One launch-ACL entry: a principal allowed to launch as the workload. **Attributes**: * `kind` *str | Unset* - The kind of principal this entry names: `user` (an org member, named by user id — also the meaning of an unset kind) or `service_account` (a service-account API key, named by key id). Any other value is rejected. * `principal_id` *str | Unset* - The principal's stable id: a user id for `user`, a service-account key id for `service_account`.