Workspaces
122 endpoints. Paths are relative to https://api.sandscale.dev; values in braces are ones you fill in.
API reference · Authentication · Errors
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/cloud-environments | List cloud environments |
POST | /api/v1/cloud-environments | Create a cloud environment |
GET | /api/v1/cloud-environments/{id} | Get one cloud environment |
PATCH | /api/v1/cloud-environments/{id} | Update one cloud environment |
DELETE | /api/v1/cloud-environments/{id} | Delete one cloud environment |
PUT | /api/v1/cloud-environments/defaults/{product} | Replace one default |
GET | /api/v1/cloud-environments/placement | List placement |
PUT | /api/v1/cloud-environments/placement | Replaces the placement policy. The organization comes from the session, never from the body; the server validates the policy against the plan and regulated status and decides every placement again at session start. |
POST | /api/v1/cloud-environments/resolve | Answers which environment a session of a product would start with for the caller: |
GET | /api/v1/cloud-environments/settings | List settings |
PUT | /api/v1/cloud-environments/settings/self-hosted | Set self hosted |
GET | /api/v1/environments | List environments |
POST | /api/v1/environments | Create an environment |
GET | /api/v1/environments/{id} | Get one environment |
PUT | /api/v1/environments/{id}/rules | Set the rules of an environment |
POST | /api/v1/environments/{id}/sessions | Create a session for an environment |
POST | /api/v1/environments/evaluate | Create an evaluate |
POST | /api/v1/gpu/allocate | Create an allocate |
GET | /api/v1/gpu/nodes | List nodes |
POST | /api/v1/gpu/nodes | Create a node |
POST | /api/v1/gpu/nodes/{id}/drain | Drain a node |
POST | /api/v1/gpu/schedule | Create a schedule |
GET | /api/v1/gpu/utilization | List utilization |
POST | /api/v1/orgs/{id}/custom-domain | Custom domain an org |
DELETE | /api/v1/orgs/{id}/custom-domain | Delete the custom domain of an org |
POST | /api/v1/orgs/{id}/custom-domain/verify | Create a verify |
PUT | /api/v1/orgs/{orgID}/custom-domain | Keeps the route of 001180: null clears (removes) the domain; naming the active domain is accepted and changes nothing; naming any other is 403 domain_not_verified. |
DELETE | /api/v1/orgs/{orgID}/invitations/{invID} | Revokes an invitation; the caller needs workspaces:manage on the invitation's workspace. |
DELETE | /api/v1/orgs/{orgID}/shares/{shareID} | Removes a share record; the caller needs workspaces:manage on the share's workspace. |
PUT | /api/v1/orgs/{orgID}/subdomain | Updates an organization's subdomain |
GET | /api/v1/orgs/{orgID}/templates | List the templates of an org |
POST | /api/v1/orgs/{orgID}/templates | Makes a template. A JSON body creates it empty or from a built-in template ("builtin"); an application/zip or application/octet-stream body is a bundle imported as its first version, with the template's fields in the query (name, description, access, version_name, version_message). |
GET | /api/v1/orgs/{orgID}/templates/{id} | Get one template |
PATCH | /api/v1/orgs/{orgID}/templates/{id} | Update one template |
DELETE | /api/v1/orgs/{orgID}/templates/{id} | Delete one template |
GET | /api/v1/orgs/{orgID}/templates/{id}/access | Access of a template |
PUT | /api/v1/orgs/{orgID}/templates/{id}/access | Set the access of a template |
POST | /api/v1/orgs/{orgID}/templates/{id}/deprecate | Deprecate a template |
GET | /api/v1/orgs/{orgID}/templates/{id}/launch | Answers what the caller may choose when creating a workspace from the template: its parameters with the values Sandscale accepts and the sizes within the deployment's maxima. |
GET | /api/v1/orgs/{orgID}/templates/{id}/permissions | List the permissions of a template |
PUT | /api/v1/orgs/{orgID}/templates/{id}/permissions | Set the permissions of a template |
DELETE | /api/v1/orgs/{orgID}/templates/{id}/permissions/{subjectID} | Delete one permission |
GET | /api/v1/orgs/{orgID}/templates/{id}/stats | Stats of a template |
POST | /api/v1/orgs/{orgID}/templates/{id}/undeprecate | Undeprecate a template |
GET | /api/v1/orgs/{orgID}/templates/{id}/versions | List the versions of a template |
POST | /api/v1/orgs/{orgID}/templates/{id}/versions | Takes a bundle as multipart/form-data (field "archive", with "name" and "message"), or as an application/zip or application/octet-stream body with name and message in the query. |
GET | /api/v1/orgs/{orgID}/templates/{id}/versions/{vid} | Get one version |
POST | /api/v1/orgs/{orgID}/templates/{id}/versions/{vid}/activate | Activate a version |
GET | /api/v1/orgs/{orgID}/templates/{id}/versions/{vid}/archive | Archive of a version |
GET | /api/v1/orgs/{orgID}/templates/{id}/versions/{vid}/parameters | List the parameters of a version |
GET | /api/v1/orgs/{orgID}/templates/builtins | List builtins |
GET | /api/v1/orgs/{orgID}/terraform/drift/{workspace} | Retrieves the latest drift result. |
POST | /api/v1/orgs/{orgID}/terraform/drift/{workspace} | Performs drift detection. |
POST | /api/v1/orgs/{orgID}/terraform/import | Imports an existing resource. |
GET | /api/v1/orgs/{orgID}/terraform/imports | Lists imports for a workspace. |
GET | /api/v1/orgs/{orgID}/terraform/lock/{workspace} | Retrieves the current lock. |
POST | /api/v1/orgs/{orgID}/terraform/lock/{workspace} | Acquires a state lock. |
DELETE | /api/v1/orgs/{orgID}/terraform/lock/{workspace} | Releases a state lock. |
DELETE | /api/v1/orgs/{orgID}/terraform/lock/{workspace}/force | ForceUnlock forcibly releases a lock (admin operation). |
GET | /api/v1/orgs/{orgID}/terraform/operations | Lists operations for a workspace. |
GET | /api/v1/orgs/{orgID}/terraform/plans | Lists plans for a workspace. |
POST | /api/v1/orgs/{orgID}/terraform/plans | Creates a new execution plan. |
GET | /api/v1/orgs/{orgID}/terraform/plans/{planID} | Retrieves a plan by ID. |
POST | /api/v1/orgs/{orgID}/terraform/plans/{planID}/apply | Marks a plan as applied. |
GET | /api/v1/orgs/{orgID}/terraform/resources | Lists Terraform-managed resources. |
GET | /api/v1/orgs/{orgID}/terraform/resources/{resourceID} | Retrieves a resource by ID. |
POST | /api/v1/orgs/{orgID}/terraform/resources/{resourceID}/taint | Marks a resource as tainted. |
DELETE | /api/v1/orgs/{orgID}/terraform/resources/{resourceID}/taint | Removes the taint from a resource. |
GET | /api/v1/orgs/{orgID}/terraform/state/{workspace} | Retrieves the current Terraform state. |
POST | /api/v1/orgs/{orgID}/terraform/state/{workspace} | Creates or updates Terraform state. |
GET | /api/v1/orgs/{orgID}/terraform/state/{workspace}/versions | Lists historical state versions. |
DELETE | /api/v1/orgs/{orgID}/tokens/{tokenID} | Delete one token |
POST | /api/v1/orgs/{orgID}/workspaceapps/authorize | For the console's server, with the person's access token: the origin must be exactly an app origin of this cell (<slug>--<short_id>.<cell domain>, nothing else: no path, query, user or other port), its short ID a workspace of the person's organization, and the decision allow it. The answer is the callback URL with a single-use code bound to the person, the workspace, the app and the browser's state. Every answer, granted or refused, is audited (phase "authorize"). |
GET | /api/v1/orgs/{orgID}/workspaces | List the workspaces of an org |
POST | /api/v1/orgs/{orgID}/workspaces | Create a workspace for an org |
GET | /api/v1/orgs/{orgID}/workspaces/{id}/metrics | List the metrics of a workspace |
GET | /api/v1/orgs/{orgID}/workspaces/{id}/metrics/dashboard | List dashboard |
GET | /api/v1/orgs/{orgID}/workspaces/{id}/metrics/definitions | List definitions |
GET | /api/v1/orgs/{orgID}/workspaces/{id}/metrics/latest | List latest |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID} | Get one workspace |
PATCH | /api/v1/orgs/{orgID}/workspaces/{wsID} | Update one workspace |
DELETE | /api/v1/orgs/{orgID}/workspaces/{wsID} | Delete one workspace |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/agent | The agent and its latest stats, metadata and app health. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/agent/config | Environment values are write-only after save: each is returned in its masked form (set, fingerprint), never the value, to every caller including the owner. The scripts the configuration runs often carry credentials, so reading it needs workspaces:write on the workspace (Editor, Manager, workspaces:admin), not read. |
PUT | /api/v1/orgs/{orgID}/workspaces/{wsID}/agent/config | The agent picks the config up when it next starts. The scripts run as the workspace's owner, so only the owner sets them. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/agent/logs | Handles GET .../agent/logs?after=&limit=. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/agent/logs/stream | Handles GET .../agent/logs/stream: every shipped line as an SSE "log" event whose id is its ID, until the client disconnects. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/apps | For callers holding workspaces:use on the workspace. |
PATCH | /api/v1/orgs/{orgID}/workspaces/{wsID}/apps/{slug}/share | The caller must hold workspaces:manage on the workspace; public is for the workspace's owner alone and only when the organization's policy allows it; no level wider than the policy; the Editor is always its owner's. Audited before the answer (fail closed). |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/builds | List the builds of a workspace |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/builds/{buildID} | Get one build |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/builds/{buildID}/logs | Handles GET .../builds/{buildID}/logs?after=&limit=. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/builds/{buildID}/logs/stream | Handles GET .../builds/{buildID}/logs/stream: every line as an SSE "log" event whose id is its sequence, then an "end" event with the build's final state once the build is terminal and its log drained. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/connect | What the console shows about connecting to a running workspace: the SSH host and commands and the links of the IDEs the policy allows. The console renders these strings and decides nothing. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/git-credentials | Secrets are never returned. |
PUT | /api/v1/orgs/{orgID}/workspaces/{wsID}/git-credentials/{host} | Git in the workspace acts as the owner with it, so only the owner sets it. |
DELETE | /api/v1/orgs/{orgID}/workspaces/{wsID}/git-credentials/{host} | Anyone holding workspaces:secrets on the workspace may delete one (revoking a credential is an administrative action; setting one is the owner's). |
POST | /api/v1/orgs/{orgID}/workspaces/{wsID}/guest | Guest a workspace |
DELETE | /api/v1/orgs/{orgID}/workspaces/{wsID}/guest | Delete the guest of a workspace |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/invitations | List the invitations of a workspace |
POST | /api/v1/orgs/{orgID}/workspaces/{wsID}/invite | Invite a workspace |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/open | The link that opens the workspace in ide, built here from the workspace, never from the request, and only for the IDEs the organization's policy allows. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/permissions | List the permissions of a workspace |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/pty | A terminal on the workspace, for its owner only. Binary messages are terminal bytes; text messages are JSON control messages ({"type":"resize","cols":N,"rows":N} from the client; {"type":"session","id":"..."} first from the agent). A session can only be reattached by the member who started it. |
POST | /api/v1/orgs/{orgID}/workspaces/{wsID}/rebuild | Rebuild a workspace |
POST | /api/v1/orgs/{orgID}/workspaces/{wsID}/share | Share a workspace |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/shares | List the shares of a workspace |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/ssh | An SSH connection to the workspace's agent, carried as binary WebSocket messages. Only the workspace's owner may open one; the agent accepts only the owner's own SSH keys on it. |
POST | /api/v1/orgs/{orgID}/workspaces/{wsID}/ssh/certificate | A certificate for the workspace owner's public key, 10 minutes, the principal being the owner's Linux user in the workspace. Ed25519 and ECDSA P-256 keys only. |
POST | /api/v1/orgs/{orgID}/workspaces/{wsID}/start | Start a workspace |
POST | /api/v1/orgs/{orgID}/workspaces/{wsID}/stop | Stop a workspace |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/terminal | The terminal WebSocket, opened by the browser. The route is public in the route table: it carries no access token. It is accepted only from a terminal origin with a ticket (terminalTicket) for this workspace, and is decided again here with the session's current state. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/terminal/availability | Whether the caller can open the web terminal now. The route needs workspaces:use; the answer decides workspaces:ConnectTerminal, so the console shows the button only when Sandscale says it would open. |
POST | /api/v1/orgs/{orgID}/workspaces/{wsID}/terminal/tickets | A single-use ticket for the terminal WebSocket, for the console's server (with the person's access token). It needs workspaces:ConnectTerminal on the workspace, a sign-in session the stream guard can re-check, and the workspace running with its agent connected; a refusal is audited. |
GET | /api/v1/orgs/{orgID}/workspaces/{wsID}/tokens | List the tokens of a workspace |
POST | /api/v1/orgs/{orgID}/workspaces/{wsID}/tokens | Create a token for a workspace |
GET | /api/v1/orgs/{orgID}/workspaces/lifecycle-policy | List lifecycle policy |
PUT | /api/v1/orgs/{orgID}/workspaces/lifecycle-policy | Set lifecycle policy |
GET | /api/v1/orgs/{orgID}/workspaces/policy | List policy |
PUT | /api/v1/orgs/{orgID}/workspaces/policy | Fields left out stay as they are; ide_allowlist null allows every IDE. web_editor and app_max_share are the workspace apps' policy. The change is audited in its transaction. |
GET | /api/v1/orgs/{orgID}/workspaces/ssh-host-ca | Phase 2 (host certificates): until then the host key is pinned from the agent (agent.ssh_host_key) and this answers 404. TODO: sign host certificates with a per-org vault host CA role (principal neuralinverse-workspace-<id>) and return {public_key, fingerprint} here. |
POST | /api/v1/subdomains/resolve | Resolves a host header to a portal context |
Endpoints
GET /api/v1/cloud-environments
List cloud environments
- Permission
cloud.environments:use- Response
- 200: ListResult
- Errors
- 401:
unauthorized; 503:environments_not_configured
POST /api/v1/cloud-environments
Create a cloud environment
- Permission
cloud.environments:create- Request body
- Input
- Response
- 201: Environment
- Errors
- 400:
invalid_json; 401:unauthorized; 415:content_type; 503:environments_not_configured
GET /api/v1/cloud-environments/{id}
Get one cloud environment
- Permission
cloud.environments:read- Path parameters
id- Response
- 200: Environment
- Errors
- 401:
unauthorized; 503:environments_not_configured
PATCH /api/v1/cloud-environments/{id}
Update one cloud environment
- Permission
cloud.environments:write- Path parameters
id- Request body
- Input
- Response
- 200: Environment
- Errors
- 400:
invalid_json; 401:unauthorized; 415:content_type; 503:environments_not_configured
DELETE /api/v1/cloud-environments/{id}
Delete one cloud environment
- Permission
cloud.environments:manage- Path parameters
id- Errors
- 401:
unauthorized; 503:environments_not_configured
PUT /api/v1/cloud-environments/defaults/{product}
Replace one default
GET /api/v1/cloud-environments/placement
List placement
- Permission
cloud.environments.settings:read- Response
- 200: PlacementSettings
- Errors
- 401:
unauthorized; 503:environments_not_configured
PUT /api/v1/cloud-environments/placement
Replaces the placement policy. The organization comes from the session, never from the body; the server validates the policy against the plan and regulated status and decides every placement again at session start.
- Permission
cloud.environments.settings:manage- Request body
- object
- Response
- 200: PlacementSettings
- Errors
- 400:
invalid_json; 401:unauthorized; 403:elevation_required; 415:content_type; 503:environments_not_configured
POST /api/v1/cloud-environments/resolve
Answers which environment a session of a product would start with for the caller:
- Permission
cloud.environments:use- Request body
- object
- Response
- 200: Resolution
- Errors
- 400:
invalid_json; 401:unauthorized; 415:content_type; 503:environments_not_configured
GET /api/v1/cloud-environments/settings
List settings
- Permission
cloud.environments.settings:read- Response
- 200: Settings
- Errors
- 401:
unauthorized; 503:environments_not_configured
PUT /api/v1/cloud-environments/settings/self-hosted
Set self hosted
GET /api/v1/environments
List environments
- Permission
api:access- Query parameters
project_id- Response
- 200: object of any
- Errors
- 401:
unauthorized
POST /api/v1/environments
Create an environment
- Permission
governance:manage- Request body
- object
- Response
- 201: object of any
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 415:content_type
GET /api/v1/environments/{id}
Get one environment
- Permission
api:access- Path parameters
id- Response
- 200: object of any
- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found
PUT /api/v1/environments/{id}/rules
Set the rules of an environment
- Permission
governance:manage- Path parameters
id- Request body
- EnvironmentRules
- Response
- 200: object of any
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 404:not_found; 415:content_type
POST /api/v1/environments/{id}/sessions
Create a session for an environment
- Permission
api:access- Path parameters
id- Request body
- object
- Response
- 200: object of any
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 404:not_found; 415:content_type
POST /api/v1/environments/evaluate
Create an evaluate
- Permission
api:access- Request body
- object
- Response
- 200: object of any
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 415:content_type
POST /api/v1/gpu/allocate
Create an allocate
- Permission
compute:admin- Request body
- GPUAllocation
- Response
- 201: GPUAllocation
- Errors
- 400:
invalid_json,invalid_request; 401:unauthorized; 404:not_found; 409:no_capacity; 415:content_type
GET /api/v1/gpu/nodes
List nodes
- Permission
api:access- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 404:not_found; 409:no_capacity
POST /api/v1/gpu/nodes
Create a node
POST /api/v1/gpu/nodes/{id}/drain
Drain a node
- Permission
compute:admin- Path parameters
id- Errors
- 400:
invalid_request; 401:unauthorized; 404:not_found; 409:no_capacity
POST /api/v1/gpu/schedule
Create a schedule
GET /api/v1/gpu/utilization
List utilization
- Permission
api:access- Response
- 200: object of any
- Errors
- 400:
invalid_request; 401:unauthorized; 404:not_found; 409:no_capacity
POST /api/v1/orgs/{id}/custom-domain
Custom domain an org
- Permission
organizations:update- Path parameters
id- Request body
- object
- Response
- 201: Domain
- Errors
- 400:
domain_invalid,domain_refused,invalid_request; 401:unauthorized; 404:not_found; 409:domain_taken; 422:dns_records_not_found; 503:audit_unavailable,custom_domains_not_configured,dns_unavailable,unavailable
DELETE /api/v1/orgs/{id}/custom-domain
Delete the custom domain of an org
- Permission
organizations:update- Path parameters
id- Errors
- 400:
domain_invalid,domain_refused,invalid_request; 401:unauthorized; 404:not_found; 409:domain_taken; 422:dns_records_not_found; 503:audit_unavailable,custom_domains_not_configured,dns_unavailable,unavailable
POST /api/v1/orgs/{id}/custom-domain/verify
Create a verify
- Permission
organizations:update- Path parameters
id- Response
- 200: Domain
- Errors
- 400:
domain_invalid,domain_refused,invalid_request; 401:unauthorized; 404:not_found; 409:domain_taken; 422:dns_records_not_found; 503:audit_unavailable,custom_domains_not_configured,dns_unavailable,unavailable
PUT /api/v1/orgs/{orgID}/custom-domain
Keeps the route of 001180: null clears (removes) the domain; naming the active domain is accepted and changes nothing; naming any other is 403 domain_not_verified.
- Permission
organizations:update- Path parameters
orgID- Request body
- object
- Response
- 200: object of string
- Errors
- 400:
domain_invalid,domain_refused,invalid_request; 401:unauthorized; 403:domain_not_verified; 404:not_found; 409:domain_taken; 422:dns_records_not_found; 503:audit_unavailable,custom_domains_not_configured,dns_unavailable,unavailable
DELETE /api/v1/orgs/{orgID}/invitations/{invID}
Revokes an invitation; the caller needs workspaces:manage on the invitation's workspace.
- Permission
api:access- Path parameters
orgID,invID- Errors
- 401:
unauthorized; 404:not_found; 503:authorization_unavailable
DELETE /api/v1/orgs/{orgID}/shares/{shareID}
Removes a share record; the caller needs workspaces:manage on the share's workspace.
- Permission
workspaces:manage- Path parameters
orgID,shareID- Errors
- 401:
unauthorized; 404:not_found; 503:authorization_unavailable
PUT /api/v1/orgs/{orgID}/subdomain
Updates an organization's subdomain
- Permission
organizations:update- Path parameters
orgID- Request body
- object
- Response
- 200: object of string
- Errors
- 401:
unauthorized
GET /api/v1/orgs/{orgID}/templates
List the templates of an org
- Permission
api:access- Path parameters
orgID- Query parameters
cursor,include_deleted,limit- Response
- 200: List
- Errors
- 400:
invalid_cursor,invalid_query; 404:template_not_found
POST /api/v1/orgs/{orgID}/templates
Makes a template. A JSON body creates it empty or from a built-in template ("builtin"); an application/zip or application/octet-stream body is a bundle imported as its first version, with the template's fields in the query (name, description, access, version_name, version_message).
- Permission
workspaces.templates:manage- Path parameters
orgID- Query parameters
access,description,icon,name,version_message,version_name- Request body
- templatesCreateTemplateRequest
- Response
- 201: object of any
- Errors
- 400:
invalid_json; 404:template_not_found; 413:archive_too_large; 415:content_type
GET /api/v1/orgs/{orgID}/templates/{id}
Get one template
- Permission
api:access- Path parameters
orgID,id- Response
- 200: object of any
- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
PATCH /api/v1/orgs/{orgID}/templates/{id}
Update one template
- Permission
workspaces.templates:manage- Path parameters
orgID,id- Request body
- updateTemplateRequest
- Errors
- 400:
invalid_json,invalid_uuid,missing_param; 404:template_not_found; 415:content_type
DELETE /api/v1/orgs/{orgID}/templates/{id}
Delete one template
- Permission
workspaces.templates:manage- Path parameters
orgID,id- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
GET /api/v1/orgs/{orgID}/templates/{id}/access
Access of a template
- Permission
workspaces.templates:manage- Path parameters
orgID,id- Response
- 200: AccessView
- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
PUT /api/v1/orgs/{orgID}/templates/{id}/access
Set the access of a template
- Permission
workspaces.templates:manage- Path parameters
orgID,id- Request body
- setAccessRequest
- Response
- 200: AccessView
- Errors
- 400:
invalid_json,invalid_uuid,missing_param; 404:template_not_found; 415:content_type
POST /api/v1/orgs/{orgID}/templates/{id}/deprecate
Deprecate a template
- Permission
workspaces.templates:manage- Path parameters
orgID,id- Request body
- deprecateRequest
- Errors
- 400:
invalid_json,invalid_uuid,missing_param; 404:template_not_found; 415:content_type
GET /api/v1/orgs/{orgID}/templates/{id}/launch
Answers what the caller may choose when creating a workspace from the template: its parameters with the values Sandscale accepts and the sizes within the deployment's maxima.
- Permission
api:access- Path parameters
orgID,id- Query parameters
version- Response
- 200: LaunchView
- Errors
- 400:
invalid_uuid,invalid_version,missing_param; 404:template_not_found
GET /api/v1/orgs/{orgID}/templates/{id}/permissions
List the permissions of a template
- Permission
workspaces.templates:manage- Path parameters
orgID,id- Response
- 200: object of any
- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
PUT /api/v1/orgs/{orgID}/templates/{id}/permissions
Set the permissions of a template
- Permission
workspaces.templates:manage- Path parameters
orgID,id- Request body
- setPermissionRequest
- Response
- 200: AccessView
- Errors
- 400:
invalid_json,invalid_subject_id,invalid_uuid,missing_param; 404:template_not_found; 415:content_type
DELETE /api/v1/orgs/{orgID}/templates/{id}/permissions/{subjectID}
Delete one permission
- Permission
workspaces.templates:manage- Path parameters
orgID,id,subjectID- Query parameters
subject_type- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
GET /api/v1/orgs/{orgID}/templates/{id}/stats
Stats of a template
- Permission
api:access- Path parameters
orgID,id- Response
- 200: object of any
- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
POST /api/v1/orgs/{orgID}/templates/{id}/undeprecate
Undeprecate a template
- Permission
workspaces.templates:manage- Path parameters
orgID,id- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
GET /api/v1/orgs/{orgID}/templates/{id}/versions
List the versions of a template
- Permission
api:access- Path parameters
orgID,id- Query parameters
include_archived- Response
- 200: object of any
- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
POST /api/v1/orgs/{orgID}/templates/{id}/versions
Takes a bundle as multipart/form-data (field "archive", with "name" and "message"), or as an application/zip or application/octet-stream body with name and message in the query.
- Permission
workspaces.templates:manage- Path parameters
orgID,id- Query parameters
message,name- Response
- 201: object of any
- Errors
- 400:
invalid_request,invalid_uuid,missing_param,validation_error; 404:template_not_found; 413:archive_too_large; 415:content_type
GET /api/v1/orgs/{orgID}/templates/{id}/versions/{vid}
Get one version
- Permission
api:access- Path parameters
orgID,id,vid- Response
- 200: object of any
- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
POST /api/v1/orgs/{orgID}/templates/{id}/versions/{vid}/activate
Activate a version
- Permission
workspaces.templates:manage- Path parameters
orgID,id,vid- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
GET /api/v1/orgs/{orgID}/templates/{id}/versions/{vid}/archive
Archive of a version
- Permission
workspaces.templates:manage- Path parameters
orgID,id,vid- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
GET /api/v1/orgs/{orgID}/templates/{id}/versions/{vid}/parameters
List the parameters of a version
- Permission
api:access- Path parameters
orgID,id,vid- Response
- 200: object of any
- Errors
- 400:
invalid_uuid,missing_param; 404:template_not_found
GET /api/v1/orgs/{orgID}/templates/builtins
List builtins
- Permission
workspaces.templates:manage- Path parameters
orgID- Response
- 200: object of any
- Errors
- 404:
template_not_found
GET /api/v1/orgs/{orgID}/terraform/drift/{workspace}
Retrieves the latest drift result.
- Permission
api:access- Path parameters
orgID,workspace
POST /api/v1/orgs/{orgID}/terraform/drift/{workspace}
Performs drift detection.
- Permission
api:access- Path parameters
orgID,workspace
POST /api/v1/orgs/{orgID}/terraform/import
Imports an existing resource.
- Permission
infra:manage- Path parameters
orgID- Request body
- ImportResourceRequest
GET /api/v1/orgs/{orgID}/terraform/imports
Lists imports for a workspace.
- Permission
api:access- Path parameters
orgID- Query parameters
limit,offset,workspace
GET /api/v1/orgs/{orgID}/terraform/lock/{workspace}
Retrieves the current lock.
- Permission
infra:manage- Path parameters
orgID,workspace
POST /api/v1/orgs/{orgID}/terraform/lock/{workspace}
Acquires a state lock.
- Permission
infra:manage- Path parameters
orgID,workspace- Request body
- AcquireLockRequest
DELETE /api/v1/orgs/{orgID}/terraform/lock/{workspace}
Releases a state lock.
- Permission
infra:manage- Path parameters
orgID,workspace- Request body
- ReleaseLockRequest
DELETE /api/v1/orgs/{orgID}/terraform/lock/{workspace}/force
ForceUnlock forcibly releases a lock (admin operation).
- Permission
infra:manage- Path parameters
orgID,workspace
GET /api/v1/orgs/{orgID}/terraform/operations
Lists operations for a workspace.
- Permission
api:access- Path parameters
orgID- Query parameters
limit,offset,workspace
GET /api/v1/orgs/{orgID}/terraform/plans
Lists plans for a workspace.
- Permission
api:access- Path parameters
orgID- Query parameters
limit,offset,workspace
POST /api/v1/orgs/{orgID}/terraform/plans
Creates a new execution plan.
- Permission
infra:manage- Path parameters
orgID- Request body
- CreatePlanRequest
GET /api/v1/orgs/{orgID}/terraform/plans/{planID}
Retrieves a plan by ID.
- Permission
api:access- Path parameters
orgID,planID
POST /api/v1/orgs/{orgID}/terraform/plans/{planID}/apply
Marks a plan as applied.
- Permission
infra:manage- Path parameters
orgID,planID
GET /api/v1/orgs/{orgID}/terraform/resources
Lists Terraform-managed resources.
- Permission
api:access- Path parameters
orgID- Query parameters
limit,offset,state,type,workspace
GET /api/v1/orgs/{orgID}/terraform/resources/{resourceID}
Retrieves a resource by ID.
- Permission
api:access- Path parameters
orgID,resourceID
POST /api/v1/orgs/{orgID}/terraform/resources/{resourceID}/taint
Marks a resource as tainted.
- Permission
infra:manage- Path parameters
orgID,resourceID- Request body
- object
DELETE /api/v1/orgs/{orgID}/terraform/resources/{resourceID}/taint
Removes the taint from a resource.
- Permission
infra:manage- Path parameters
orgID,resourceID
GET /api/v1/orgs/{orgID}/terraform/state/{workspace}
Retrieves the current Terraform state.
- Permission
infra:manage- Path parameters
orgID,workspace- Errors
- 503:
audit_unavailable
POST /api/v1/orgs/{orgID}/terraform/state/{workspace}
Creates or updates Terraform state.
- Permission
infra:manage- Path parameters
orgID,workspace
GET /api/v1/orgs/{orgID}/terraform/state/{workspace}/versions
Lists historical state versions.
- Permission
infra:manage- Path parameters
orgID,workspace- Query parameters
limit,offset- Errors
- 503:
audit_unavailable
DELETE /api/v1/orgs/{orgID}/tokens/{tokenID}
Delete one token
- Permission
workspaces:manage- Path parameters
orgID,tokenID- Errors
- 401:
unauthorized; 404:not_found; 503:authorization_unavailable
POST /api/v1/orgs/{orgID}/workspaceapps/authorize
For the console's server, with the person's access token: the origin must be exactly an app origin of this cell (<slug>--<short_id>.<cell domain>, nothing else: no path, query, user or other port), its short ID a workspace of the person's organization, and the decision allow it. The answer is the callback URL with a single-use code bound to the person, the workspace, the app and the browser's state. Every answer, granted or refused, is audited (phase "authorize").
- Permission
api:access- Path parameters
orgID- Request body
- authorizeBody
- Response
- 201: object of any
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 403:client_not_console,session_required; 404:app_not_found,not_found; 415:content_type; 429:too_many_tickets; 503:apps_unavailable,audit_unavailable
GET /api/v1/orgs/{orgID}/workspaces
List the workspaces of an org
- Permission
workspaces:use- Path parameters
orgID- Query parameters
all,cursor,limit,project_id- Response
- 200: workspaceListResponse
- Errors
- 400:
invalid_cursor,invalid_limit,invalid_repository,invalid_transition; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
POST /api/v1/orgs/{orgID}/workspaces
Create a workspace for an org
- Permission
workspaces:create- Path parameters
orgID- Request body
- createWorkspaceRequest
- Response
- 201: createWorkspaceResponse
- Errors
- 400:
invalid_json,invalid_repository,invalid_template_id,invalid_transition,invalid_version_id; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 415:content_type; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
GET /api/v1/orgs/{orgID}/workspaces/{id}/metrics
List the metrics of a workspace
- Permission
workspaces:read- Path parameters
orgID,id- Query parameters
aggregation,end,interval,metric,start
GET /api/v1/orgs/{orgID}/workspaces/{id}/metrics/dashboard
List dashboard
- Permission
workspaces:read- Path parameters
orgID,id- Query parameters
duration
GET /api/v1/orgs/{orgID}/workspaces/{id}/metrics/definitions
List definitions
- Permission
workspaces:read- Path parameters
orgID,id
GET /api/v1/orgs/{orgID}/workspaces/{id}/metrics/latest
List latest
- Permission
workspaces:read- Path parameters
orgID,id
GET /api/v1/orgs/{orgID}/workspaces/{wsID}
Get one workspace
- Permission
workspaces:read- Path parameters
orgID,wsID- Response
- 200: workspaceResponse
- Errors
- 400:
invalid_repository,invalid_transition; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
PATCH /api/v1/orgs/{orgID}/workspaces/{wsID}
Update one workspace
- Permission
workspaces:write- Path parameters
orgID,wsID- Request body
- updateWorkspaceRequest
- Response
- 200: workspaceResponse
- Errors
- 400:
invalid_json,invalid_repository,invalid_transition; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 415:content_type; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
DELETE /api/v1/orgs/{orgID}/workspaces/{wsID}
Delete one workspace
- Permission
workspaces:manage- Path parameters
orgID,wsID- Errors
- 400:
invalid_repository,invalid_transition; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/agent
The agent and its latest stats, metadata and app health.
- Permission
workspaces:read- Path parameters
orgID,wsID- Response
- 200: object of any
- Errors
- 400:
validation_error; 401:unauthorized; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 503:authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/agent/config
Environment values are write-only after save: each is returned in its masked form (set, fingerprint), never the value, to every caller including the owner. The scripts the configuration runs often carry credentials, so reading it needs workspaces:write on the workspace (Editor, Manager, workspaces:admin), not read.
- Permission
workspaces:write- Path parameters
orgID,wsID- Errors
- 400:
validation_error; 401:unauthorized; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 503:authorization_unavailable,unavailable
PUT /api/v1/orgs/{orgID}/workspaces/{wsID}/agent/config
The agent picks the config up when it next starts. The scripts run as the workspace's owner, so only the owner sets them.
- Permission
workspaces:write- Path parameters
orgID,wsID- Request body
- agentConfigBody
- Errors
- 400:
invalid_json,validation_error; 402:quota_exceeded; 403:forbidden,owner_only; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 415:content_type; 503:authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/agent/logs
Handles GET .../agent/logs?after=&limit=.
- Permission
workspaces:write- Path parameters
orgID,wsID- Query parameters
after,limit- Response
- 200: agentLogPage
- Errors
- 400:
validation_error; 401:unauthorized; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 503:authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/agent/logs/stream
Handles GET .../agent/logs/stream: every shipped line as an SSE "log" event whose id is its ID, until the client disconnects.
- Permission
workspaces:write- Path parameters
orgID,wsID- Query parameters
after,limit- Errors
- 400:
validation_error; 401:session_required,unauthorized; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 429:too_many_streams; 503:authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/apps
For callers holding workspaces:use on the workspace.
- Permission
workspaces:use- Path parameters
orgID,wsID- Response
- 200: object of any
- Errors
- 401:
unauthorized; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 503:apps_unavailable,authorization_unavailable,unavailable
PATCH /api/v1/orgs/{orgID}/workspaces/{wsID}/apps/{slug}/share
The caller must hold workspaces:manage on the workspace; public is for the workspace's owner alone and only when the organization's policy allows it; no level wider than the policy; the Editor is always its owner's. Audited before the answer (fail closed).
- Permission
workspaces:manage- Path parameters
orgID,wsID,slug- Request body
- setShareBody
- Response
- 200: object of any
- Errors
- 400:
invalid_json,invalid_share; 401:unauthorized; 402:quota_exceeded; 403:forbidden,owner_only,policy_denied; 404:app_not_found,not_found; 409:build_in_progress,fixed_share,managed_by_build_lease; 410:workspace_deleted; 415:content_type; 503:apps_unavailable,audit_unavailable,authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/builds
List the builds of a workspace
- Permission
workspaces:read- Path parameters
orgID,wsID- Query parameters
limit- Response
- 200: buildListResponse
- Errors
- 400:
invalid_repository,invalid_transition; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/builds/{buildID}
Get one build
- Permission
workspaces:read- Path parameters
orgID,wsID,buildID- Response
- 200: buildResponse
- Errors
- 400:
invalid_repository,invalid_transition; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/builds/{buildID}/logs
Handles GET .../builds/{buildID}/logs?after=&limit=.
- Permission
workspaces:write- Path parameters
orgID,wsID,buildID- Query parameters
after,limit- Response
- 200: buildLogPage
- Errors
- 400:
validation_error; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 503:authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/builds/{buildID}/logs/stream
Handles GET .../builds/{buildID}/logs/stream: every line as an SSE "log" event whose id is its sequence, then an "end" event with the build's final state once the build is terminal and its log drained.
- Permission
workspaces:write- Path parameters
orgID,wsID,buildID- Query parameters
after,limit- Errors
- 400:
validation_error; 401:session_required; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 429:too_many_streams; 503:authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/connect
What the console shows about connecting to a running workspace: the SSH host and commands and the links of the IDEs the policy allows. The console renders these strings and decides nothing.
- Permission
workspaces:use- Path parameters
orgID,wsID- Response
- 200: object of any
- Errors
- 402:
quota_exceeded; 403:forbidden,kill_switch,not_authorized; 404:not_found; 409:build_in_progress,workspace_not_running; 410:workspace_deleted; 503:authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/git-credentials
Secrets are never returned.
- Permission
workspaces:read- Path parameters
orgID,wsID- Response
- 200: object of any
- Errors
- 400:
validation_error; 401:unauthorized; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 503:authorization_unavailable,unavailable
PUT /api/v1/orgs/{orgID}/workspaces/{wsID}/git-credentials/{host}
Git in the workspace acts as the owner with it, so only the owner sets it.
- Permission
workspaces:secrets- Path parameters
orgID,wsID,host- Request body
- gitCredentialBody
- Response
- 200: GitCredential
- Errors
- 400:
invalid_json,validation_error; 402:quota_exceeded; 403:forbidden,owner_only; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 415:content_type; 503:authorization_unavailable,unavailable
DELETE /api/v1/orgs/{orgID}/workspaces/{wsID}/git-credentials/{host}
Anyone holding workspaces:secrets on the workspace may delete one (revoking a credential is an administrative action; setting one is the owner's).
- Permission
workspaces:secrets- Path parameters
orgID,wsID,host- Errors
- 400:
validation_error; 401:unauthorized; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 503:authorization_unavailable,unavailable
POST /api/v1/orgs/{orgID}/workspaces/{wsID}/guest
Guest a workspace
- Permission
workspaces:manage- Path parameters
orgID,wsID- Request body
- enableGuestAccessRequest
- Response
- 200: guestAccessResponse
- Errors
- 401:
unauthorized; 404:not_found; 409:managed_by_build_lease; 503:audit_unavailable,authorization_unavailable,unavailable
DELETE /api/v1/orgs/{orgID}/workspaces/{wsID}/guest
Delete the guest of a workspace
- Permission
workspaces:manage- Path parameters
orgID,wsID- Errors
- 401:
unauthorized; 404:not_found; 503:authorization_unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/invitations
List the invitations of a workspace
- Permission
workspaces:read- Path parameters
orgID,wsID- Response
- 200: invitationResponse
- Errors
- 401:
unauthorized; 404:not_found; 503:authorization_unavailable
POST /api/v1/orgs/{orgID}/workspaces/{wsID}/invite
Invite a workspace
- Permission
workspaces:manage- Path parameters
orgID,wsID- Request body
- createInvitationRequest
- Response
- 201: invitationResponse
- Errors
- 401:
unauthorized; 404:not_found; 409:managed_by_build_lease; 503:audit_unavailable,authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/open
The link that opens the workspace in ide, built here from the workspace, never from the request, and only for the IDEs the organization's policy allows.
- Permission
workspaces:use- Path parameters
orgID,wsID- Query parameters
ide- Response
- 200: object of any
- Errors
- 400:
ide_unsupported; 402:quota_exceeded; 403:forbidden,kill_switch,not_authorized,policy_denied; 404:not_found; 409:build_in_progress,web_editor_unavailable,workspace_not_running; 410:workspace_deleted; 503:authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/permissions
List the permissions of a workspace
- Permission
workspaces:read- Path parameters
orgID,wsID- Response
- 200: permissionResponse
- Errors
- 401:
unauthorized; 404:not_found; 503:authorization_unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/pty
A terminal on the workspace, for its owner only. Binary messages are terminal bytes; text messages are JSON control messages ({"type":"resize","cols":N,"rows":N} from the client; {"type":"session","id":"..."} first from the agent). A session can only be reattached by the member who started it.
- Permission
workspaces:use- Path parameters
orgID,wsID- Query parameters
command,session- Errors
- 400:
validation_error; 401:session_required; 402:quota_exceeded; 403:forbidden,owner_only; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 429:too_many_streams; 503:agent_not_connected,authorization_unavailable,relay_peer_unreachable,relay_unavailable,unavailable; 504:agent_timeout
POST /api/v1/orgs/{orgID}/workspaces/{wsID}/rebuild
Rebuild a workspace
- Permission
workspaces:use- Path parameters
orgID,wsID- Request body
- rebuildWorkspaceRequest
- Response
- 202: buildResponse
- Errors
- 400:
invalid_json,invalid_repository,invalid_transition,invalid_version_id; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 415:content_type; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
POST /api/v1/orgs/{orgID}/workspaces/{wsID}/share
Share a workspace
- Permission
workspaces:manage- Path parameters
orgID,wsID- Request body
- shareWorkspaceRequest
- Response
- 200: shareResponse
- Errors
- 401:
unauthorized; 404:not_found; 409:managed_by_build_lease; 503:audit_unavailable,authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/shares
List the shares of a workspace
- Permission
workspaces:read- Path parameters
orgID,wsID- Response
- 200: shareResponse
- Errors
- 401:
unauthorized; 404:not_found; 503:authorization_unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/ssh
An SSH connection to the workspace's agent, carried as binary WebSocket messages. Only the workspace's owner may open one; the agent accepts only the owner's own SSH keys on it.
- Permission
workspaces:use- Path parameters
orgID,wsID- Errors
- 401:
session_required; 402:quota_exceeded; 403:forbidden,kill_switch,owner_only,policy_denied; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 412:no_ssh_keys; 429:too_many_streams; 503:agent_not_connected,authorization_unavailable,relay_peer_unreachable,relay_unavailable,unavailable; 504:agent_timeout
POST /api/v1/orgs/{orgID}/workspaces/{wsID}/ssh/certificate
A certificate for the workspace owner's public key, 10 minutes, the principal being the owner's Linux user in the workspace. Ed25519 and ECDSA P-256 keys only.
- Permission
workspaces:use- Path parameters
orgID,wsID- Request body
- sshCertificateRequest
- Response
- 200: object of any
- Errors
- 400:
invalid_json,unsupported_key; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch,not_authorized,policy_denied; 404:not_found; 409:build_in_progress,login_wipe_owed,managed_by_build_lease,workspace_not_running; 410:workspace_deleted; 415:content_type; 503:audit_unavailable,authorization_unavailable,unavailable
POST /api/v1/orgs/{orgID}/workspaces/{wsID}/start
Start a workspace
- Permission
workspaces:use- Path parameters
orgID,wsID- Response
- 202: buildResponse
- Errors
- 400:
invalid_repository,invalid_transition; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
POST /api/v1/orgs/{orgID}/workspaces/{wsID}/stop
Stop a workspace
- Permission
workspaces:use- Path parameters
orgID,wsID- Response
- 202: buildResponse
- Errors
- 400:
invalid_repository,invalid_transition; 401:unauthorized; 402:quota_exceeded; 403:forbidden,kill_switch_active,vault_references_refused; 404:not_found,project_not_found; 409:build_in_progress,conflict,managed_by_build_lease,project_inactive,stale_version,template_mismatch,workspace_state_inconsistent; 410:workspace_deleted; 503:authorization_unavailable,environments_not_configured,kill_switch_unavailable,lifecycle_policy_unavailable,projects_unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/terminal
The terminal WebSocket, opened by the browser. The route is public in the route table: it carries no access token. It is accepted only from a terminal origin with a ticket (terminalTicket) for this workspace, and is decided again here with the session's current state.
- Permission
none- Path parameters
orgID,wsID- Errors
- 400:
validation_error; 401:session_ended,unauthorized; 402:quota_exceeded; 403:forbidden,origin_refused; 404:not_found,session_not_found; 409:build_in_progress,session_expired; 410:workspace_deleted; 429:too_many_streams,too_many_terminals; 502:agent_refused; 503:agent_not_connected,authorization_unavailable,relay_peer_unreachable,relay_unavailable,terminal_unavailable,unavailable; 504:agent_timeout
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/terminal/availability
Whether the caller can open the web terminal now. The route needs workspaces:use; the answer decides workspaces:ConnectTerminal, so the console shows the button only when Sandscale says it would open.
- Permission
workspaces:use- Path parameters
orgID,wsID- Response
- 200: terminalAvailability
- Errors
- 401:
unauthorized; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress; 410:workspace_deleted; 503:authorization_unavailable,unavailable
POST /api/v1/orgs/{orgID}/workspaces/{wsID}/terminal/tickets
A single-use ticket for the terminal WebSocket, for the console's server (with the person's access token). It needs workspaces:ConnectTerminal on the workspace, a sign-in session the stream guard can re-check, and the workspace running with its agent connected; a refusal is audited.
- Permission
workspaces:connectterminal- Path parameters
orgID,wsID- Request body
- terminalTicketBody
- Response
- 201: object of any
- Errors
- 400:
invalid_json,validation_error; 401:session_required,unauthorized; 402:quota_exceeded; 403:forbidden; 404:not_found; 409:build_in_progress,session_expired; 410:workspace_deleted; 415:content_type; 429:too_many_tickets; 503:authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/{wsID}/tokens
List the tokens of a workspace
- Permission
workspaces:manage- Path parameters
orgID,wsID- Response
- 200: accessTokenResponse
- Errors
- 401:
unauthorized; 404:not_found; 503:authorization_unavailable
POST /api/v1/orgs/{orgID}/workspaces/{wsID}/tokens
Create a token for a workspace
- Permission
workspaces:manage- Path parameters
orgID,wsID- Request body
- createAccessTokenRequest
- Response
- 201: accessTokenResponse
- Errors
- 401:
unauthorized; 404:not_found; 409:managed_by_build_lease; 503:audit_unavailable,authorization_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/lifecycle-policy
List lifecycle policy
- Permission
api:access- Path parameters
orgID- Response
- 200: lifecyclePolicyResponse
- Errors
- 401:
unauthorized; 404:not_found; 503:lifecycle_policy_unavailable
PUT /api/v1/orgs/{orgID}/workspaces/lifecycle-policy
Set lifecycle policy
- Permission
workspaces.lifecycle:manage- Path parameters
orgID- Request body
- lifecyclePolicyBody
- Response
- 200: lifecyclePolicyResponse
- Errors
- 400:
invalid_json; 401:unauthorized; 404:not_found; 409:stale_version; 415:content_type; 503:audit_unavailable,lifecycle_policy_unavailable,step_up_unavailable
GET /api/v1/orgs/{orgID}/workspaces/policy
List policy
- Permission
api:access- Path parameters
orgID- Response
- 200: object of any
- Errors
- 401:
unauthorized; 404:not_found; 503:unavailable
PUT /api/v1/orgs/{orgID}/workspaces/policy
Fields left out stay as they are; ide_allowlist null allows every IDE. web_editor and app_max_share are the workspace apps' policy. The change is audited in its transaction.
- Permission
governance:manage- Path parameters
orgID- Request body
- putWorkspacePolicyRequest
- Response
- 200: object of any
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 404:not_found; 415:content_type; 503:audit_unavailable,unavailable
GET /api/v1/orgs/{orgID}/workspaces/ssh-host-ca
Phase 2 (host certificates): until then the host key is pinned from the agent (agent.ssh_host_key) and this answers 404. TODO: sign host certificates with a per-org vault host CA role (principal neuralinverse-workspace-<id>) and return {public_key, fingerprint} here.
- Permission
api:access- Path parameters
orgID- Errors
- 401:
unauthorized; 404:not_enabled,not_found
POST /api/v1/subdomains/resolve
Resolves a host header to a portal context
- Permission
api:access- Request body
- object
- Response
- 200: PortalContext; 200: PublicPortalContext
Objects
object
| Field | Type | Description |
|---|---|---|
product | string | |
environment_id | string |
object
| Field | Type | Description |
|---|---|---|
project_id optional | string | |
name | string | |
custom_name | string | |
rules optional | EnvironmentRules |
object
| Field | Type | Description |
|---|---|---|
session_id | string | |
model | string | |
operation | string | |
cost_so_far | number |
object
| Field | Type | Description |
|---|---|---|
session_id | string | |
agent_id | string | |
user_id optional | string |
object
| Field | Type | Description |
|---|---|---|
domain | string |
object
| Field | Type | Description |
|---|---|---|
reason | string |
object
| Field | Type | Description |
|---|---|---|
host | string |
object
| Field | Type | Description |
|---|---|---|
environment_id optional | string |
object
| Field | Type | Description |
|---|---|---|
allowed | array of string | |
preferred | string |
object
| Field | Type | Description |
|---|---|---|
allow optional | boolean |
object
| Field | Type | Description |
|---|---|---|
custom_domain optional | string |
object
| Field | Type | Description |
|---|---|---|
subdomain optional | string |
AppCheck
A workspace app whose health the agent checks.
| Field | Type | Description |
|---|---|---|
slug | string | |
url | string | Where the app serves inside the workspace (loopback only). |
health_url optional | string | Polled every 30 seconds; empty means the app is assumed healthy while the agent runs. Loopback only. |
GitCredential
GitCredential describes a stored git credential; the secret is never part of it.
| Field | Type | Description |
|---|---|---|
host | string | |
username | string | |
updated_by | uuid | |
updated_at | timestamp |
LogEntry
One shipped log line.
| Field | Type | Description |
|---|---|---|
id | integer | |
source | string | |
level | string | |
message | string | |
logged_at | timestamp |
MetadataItem
A script whose output the agent reports under Key.
| Field | Type | Description |
|---|---|---|
key | string | |
script | string | |
interval_seconds optional | integer | |
timeout_seconds optional | integer |
Script
A lifecycle script.
| Field | Type | Description |
|---|---|---|
name | string | |
command | string | Run with /bin/sh -c as the workspace user. |
run_on | string | "startup", "shutdown" or "cron". |
cron optional | string | "@every <duration>" for cron scripts (at least one minute). |
timeout_seconds optional | integer | TimeoutSeconds bounds one run; 0 means the default of ten minutes. |
required optional | boolean | Required startup scripts that fail leave the agent in the "starting" state, so the workspace never reports ready on a broken setup. |
BYOCConnection
A BYOC connection an environment may name.
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
status | string | |
provider | string | Aws or azure; AccountID is the AWS account or Azure subscription; Region is the provider's region. |
account_id | string | |
region | string |
ComputeSourceOption
One compute source choice: available or why not.
| Field | Type | Description |
|---|---|---|
source | string | |
name | string | |
description | string | |
available | boolean | |
reason optional | string | |
connections optional | array of BYOCConnection |
EnvVar
A non-secret environment variable.
| Field | Type | Description |
|---|---|---|
name | string | |
value | string |
Environment
A cloud environment as the API returns it. Status and StatusMessage are computed when it is read; UsedBy lists the products that use it by default.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | |
name | string | |
description | string | |
compute_source | string | |
byoc_connection_id optional | string | |
template_kind optional | string | |
template_id optional | string | |
size optional | string | |
network_access | string | |
allowed_domains | array of string | |
include_trusted | boolean | |
setup_script | string | |
env_vars | array of EnvVar | |
secret_refs | array of SecretRef | |
access | string | |
status | string | |
status_message optional | string | |
revision | integer | |
last_activity_at optional | timestamp | |
used_by | array of string | |
created_by optional | string | |
updated_by optional | string | |
created_at | timestamp | |
updated_at | timestamp | |
can_edit | boolean | CanEdit and CanManage are the caller's own access, decided by access control, so the console shows only the actions the server will accept. |
can_manage | boolean |
Input
| Field | Type | Description |
|---|---|---|
name optional | string | |
description optional | string | |
compute_source optional | string | |
byoc_connection_id optional | string | |
template_kind optional | string | |
template_id optional | string | |
size optional | string | |
network_access optional | string | |
allowed_domains optional | array of string | |
include_trusted optional | boolean | |
setup_script optional | string | |
env_text optional | string | The "KEY=value" lines form of EnvVars, as the console's text box sends it. It is parsed by the server; give EnvVars or EnvText, not both. |
env_vars optional | array of EnvVar | |
secret_refs optional | array of SecretRef | |
access optional | string | |
revision optional | integer | Revision, on an update, is the revision the caller read: a concurrent change is refused (409 revision_conflict) instead of being overwritten. |
ListResult
The list of environments a caller may see: the full configuration of those they may read, a summary of those they may only use.
| Field | Type | Description |
|---|---|---|
environments | array of Environment | |
usable | array of Summary |
NetworkOption
One network access choice, as the console offers it.
| Field | Type | Description |
|---|---|---|
access | string | |
name | string | |
description | string | |
recommended optional | boolean |
PlacementSettings
The page model of Settings > Compute: the server's rules and the account's policy.
| Field | Type | Description |
|---|---|---|
plan | string | |
regulated | boolean | |
policy | Policy | |
targets | array of PlacementTarget | |
operator_default optional | string | |
can_manage | boolean | |
notes | array of string | Sentences the server wants shown (the regulated restriction). |
PlacementTarget
One place compute can run, as the console shows it.
| Field | Type | Description |
|---|---|---|
target | string | |
label | string | |
available | boolean | |
reason optional | string | Reason says why the account cannot use it. |
allowed | boolean | |
capabilities | Capabilities |
ProductDefault
One row of "Used by": a product, the environment it uses by default (or none), and what happens without one, as the server describes it.
| Field | Type | Description |
|---|---|---|
product | string | |
name | string | |
description | string | |
environment optional | Summary | |
fallback | string | Fallback says what a session of the product starts with when it has no default and the member picks none. |
QuotaView
The environments quota of the account.
| Field | Type | Description |
|---|---|---|
code | string | |
value | integer | |
usage | integer |
Resolution
What a session of a product would start with for a principal: the environment (nil: the product's built-in behaviour) and why.
| Field | Type | Description |
|---|---|---|
product | string | |
environment optional | Summary | |
source | string | "requested" (the caller named it), "default" (the product's default) or "builtin" (neither: the product's built-in behaviour, described by Fallback). |
fallback optional | string |
SecretRef
A Vault reference: the variable Name gets Field of the secret at Path, read when a session starts with the permissions of the person starting it.
| Field | Type | Description |
|---|---|---|
name | string | |
path | string | |
field | string |
Settings
The page model of Cloud environments for administrators: everything the console renders around the list.
| Field | Type | Description |
|---|---|---|
allow_self_hosted | boolean | |
updated_at optional | timestamp | |
updated_by optional | string | |
defaults | array of ProductDefault | |
trusted | TrustedList | |
sizes | array of Size | |
network_options | array of NetworkOption | |
compute_sources | array of ComputeSourceOption | |
quota | QuotaView | |
region | string | |
can_manage | boolean | |
can_create | boolean |
Size
A size the server offers.
| Field | Type | Description |
|---|---|---|
key | string | |
name | string | |
cpu_cores | integer | |
memory_gb | integer | |
disk_gb | integer |
Summary
An environment as a list shows it to a caller who may only use it: no setup script, variables or references.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | |
name | string | |
description | string | |
compute_source | string | |
network_access | string | |
size optional | string | |
access | string | |
status | string | |
status_message optional | string | |
last_activity_at optional | timestamp | |
used_by | array of string |
TrustedList
The trusted network list, read-only.
| Field | Type | Description |
|---|---|---|
version | string | |
groups | array of TrustedGroup |
Capabilities
What a provider can do and its limits. Template requirements are matched against it (Requirements.Satisfied); a limit of 0 means the provider states none.
| Field | Type | Description |
|---|---|---|
gpu | boolean | GPU: the provider can schedule GPU compute. |
nested_isolation | boolean | NestedIsolation: workloads can run in a nested isolation layer (microVMs or gVisor sandboxes inside the instance), which Sandscale sandboxes need. |
snapshots | boolean | Snapshots: Snapshot and Restore work. |
logs | boolean | Logs: Logs works. |
persistent_storage | boolean | PersistentStorage: a stopped instance's storage survives. |
max_vcpu | integer | MaxVCPU and MaxMemoryGB bound one instance. |
max_memory_gb | integer | |
regions optional | array of string | The regions the provider runs in (empty: one fixed location). |
Cost
What a resource's running time cost: in total and in the current month (UTC).
| Field | Type | Description |
|---|---|---|
total | Money | |
this_month | Money |
Money
An amount in US dollars: USD exactly (six decimals, for clients that compute), and Display as people see it. Display has two decimals ("$1,234.56"), "under $0.01" for an amount above zero that rounds below a cent, or the reason there is no amount.
| Field | Type | Description |
|---|---|---|
usd | string | |
display | string |
Runtime
The runtime a sandbox or workspace ran on.
| Field | Type | Description |
|---|---|---|
kind | string | Firecracker, docker_gvisor, docker, kubernetes, gvisor (a gVisor container whose runtime was not recorded) or not_recorded. |
label | string | The kind in words: "Firecracker microVM", "Docker (gVisor)", "Docker", "Kubernetes", "gVisor container" or "Not recorded". |
TrustedGroup
One source of the trusted list: a package registry or source host and the host names its clients reach.
| Field | Type | Description |
|---|---|---|
key | string | |
name | string | |
domains | array of string |
EnvironmentRules
EnvironmentRules defines the governance constraints for an environment.
| Field | Type | Description |
|---|---|---|
require_hitl | boolean | |
allowed_models | array of string | |
blocked_models | array of string | |
max_cost_per_session_usd | number | |
max_budget_per_day_usd | number | |
allow_agent_write | boolean | |
allow_bash_exec | boolean | |
require_approval_for_write | boolean | |
allowed_tool_scopes | array of string | |
data_class_restrictions | array of string |
GPUAllocation
GPUAllocation reserves GPU slots on a node for a team, following the available → reserved → in-use → released state machine.
| Field | Type | Description |
|---|---|---|
id | string | |
node_id | string | |
team_id | string | |
gpu_slots | integer | |
priority | integer | |
state | string | |
expires_at optional | timestamp | |
created_at | timestamp | |
updated_at | timestamp |
GPUJob
GPUJob represents a unit of work scheduled to run on a GPU node. Status lifecycle: queued → running → (completed | failed | cancelled).
| Field | Type | Description |
|---|---|---|
id | string | |
org_id | string | |
node_id | string | |
model_id | string | |
status | string | |
gpus_needed | integer | |
priority | integer | |
queued_at | timestamp | |
started_at optional | timestamp | |
finished_at optional | timestamp |
GPUNode
GPUNode represents a physical or virtual machine hosting one or more GPUs.
| Field | Type | Description |
|---|---|---|
id | string | |
org_id | string | |
hostname | string | |
gpu_type | string | |
gpu_count | integer | |
vram_per_gpu_gb | integer | |
driver_version | string | |
cuda_version | string | |
status | string | |
labels optional | object of string | |
created_at | timestamp | |
updated_at | timestamp |
Domain
An Organization's custom domain as the API shows it.
| Field | Type | Description |
|---|---|---|
id | string | |
org_id | string | |
domain | string | |
status | string | |
verified | boolean | |
verified_at optional | timestamp | |
dns_records | array of Record | |
issuer optional | string | |
last_checked_at optional | timestamp | |
last_check_result optional | string | |
failed_checks | integer | |
dns_error_since optional | timestamp | When the run of DNS errors on every check began (none: the last check got an answer). |
disabled_at optional | timestamp | |
disabled_reason optional | string | |
tls_provisioned | boolean | TLSProvisioned: the TLS edge asked for, and was allowed, a certificate for the domain. |
created_at | timestamp | |
updated_at | timestamp | |
verification_token | string | The TXT value's token (kept for the console of 001180, also in Records). Not a secret: it is published in DNS. |
Record
A DNS record the Organization publishes.
| Field | Type | Description |
|---|---|---|
type | string | |
name | string | |
value | string | |
purpose | string | Purpose says what the record proves: ownership or routing. |
Policy
The organization's own placement policy. The zero value places anywhere the rules allow.
| Field | Type | Description |
|---|---|---|
allowed | array of string | The targets the organization permits; empty means every target the rules allow. |
preferred optional | string | Tried first when it is allowed and eligible. |
PortalContext
PortalContext holds resolved portal information
| Field | Type | Description |
|---|---|---|
portal_type | string | |
org_id optional | uuid | |
org_name optional | string | |
org_slug optional | string | |
bu_id optional | uuid | |
bu_name optional | string | |
branding_id optional | string | Resolved branding config |
host | string |
PublicPortalContext
What an unrelated caller learns about a host: that it is served, and what sign-in routing needs. It never carries an organization's name, ID or branding.
| Field | Type | Description |
|---|---|---|
exists | boolean | |
portal_type | string | |
org_slug optional | string | |
host | string |
AccessView
Who may use a template, for a caller who manages templates.
| Field | Type | Description |
|---|---|---|
access | string | |
access_label | string | |
grants | array of Grant | |
grants_apply | boolean | GrantsApply says whether the grants count under the current mode. |
modes | array of ModeOption |
Grant
One explicit grant as the access panel shows it.
| Field | Type | Description |
|---|---|---|
subject_type | string | |
subject_id | uuid | |
name | string | The user's name or email, or the group's name; empty when the subject is no longer part of the organization (the grant then counts for nobody). |
current | boolean | |
role | string | |
granted_by | uuid | |
granted_at | timestamp |
LaunchParameter
One parameter as the new-workspace form shows it: the choices Sandscale accepts (size options above the deployment's maximum are left out) and the default it uses when the field is left empty.
| Field | Type | Description |
|---|---|---|
name | string | |
display_name | string | |
description | string | |
type | string | |
required | boolean | |
sensitive | boolean | |
default optional | string | |
choices optional | array of string | |
min optional | number | |
max optional | number | |
pattern optional | string | |
size optional | string | "cpu_cores" or "memory_gb" for a size parameter, else "". |
unit optional | string |
LaunchView
What the new-workspace form shows for a template.
| Field | Type | Description |
|---|---|---|
template | Summary | |
version | VersionRef | |
parameters | array of LaunchParameter | |
sizes | Sizes | |
size_limits | SizeLimits |
List
The template list for one caller.
| Field | Type | Description |
|---|---|---|
templates | array of Summary | |
next_cursor | string | |
can_manage | boolean | |
size_limits | SizeLimits |
ModeOption
An access mode with Sandscale's label for it.
| Field | Type | Description |
|---|---|---|
value | string | |
label | string |
SizeLimits
The largest workspace a member may ask for on this deployment (NI_CLOUD_WORKSPACE_MAX_CPU_CORES, NI_CLOUD_WORKSPACE_MAX_MEMORY_GB). Sandscale refuses a template version that offers more and a workspace that asks for more; there is no unlimited setting. They must not exceed the provisioner daemons' maxima (package size): registration checks the pair.
| Field | Type | Description |
|---|---|---|
max_cpu_cores | number | |
max_memory_gb | number |
SizeOffer
What one size parameter of a version lets a member choose, within the deployment's maximum.
| Field | Type | Description |
|---|---|---|
parameter | string | |
options optional | array of string | |
min optional | number | |
max | number | |
default optional | string | |
unit | string |
Sizes
What a version offers for workspace sizes, with a label Sandscale writes for people (the console shows it as is).
| Field | Type | Description |
|---|---|---|
cpu_cores optional | SizeOffer | |
memory_gb optional | SizeOffer | |
label | string |
Summary
One template as the list and the detail page show it.
| Field | Type | Description |
|---|---|---|
id | uuid | |
org_id | uuid | |
name | string | |
description | string | |
icon | string | URL or empty |
active_version_id optional | uuid | |
created_by | uuid | |
created_at | timestamp | |
updated_at | timestamp | |
deleted_at optional | timestamp | |
access | string | Access says who may create workspaces from the template. |
deprecated_at optional | timestamp | Set while the template is deprecated: it creates no new workspace; existing workspaces keep running. |
deprecated_by optional | uuid | |
deprecation_message optional | string | |
builtin optional | string | The key of the built-in template it was created from, or "". |
updated_by optional | uuid | |
nrn optional | string | The template's NRN; the API handler sets it from the owning organization's Account ID and the cell. |
status | string | |
status_label | string | |
access_label | string | |
versions | integer | |
active_version optional | VersionRef | |
sizes | Sizes | |
can_use | boolean | CanUse says whether the caller may create a workspace from it now (not deprecated, deleted or without a version, and allowed). |
can_manage | boolean | CanManage says whether the caller may change it. |
VersionRef
VersionRef names a version.
| Field | Type | Description |
|---|---|---|
id | uuid | |
name | string |
AcquireLockRequest
The request to acquire a state lock.
| Field | Type | Description |
|---|---|---|
workspace_name | string | |
lock_id | string | |
operation | string | |
who | string | |
version optional | string | |
path optional | string | |
info optional | string | |
ttl optional | integer | Seconds |
CreatePlanRequest
The request to create a plan.
| Field | Type | Description |
|---|---|---|
workspace_name | string | |
plan_json | JSON | |
terraform_version | string | |
ttl optional | integer | Seconds |
ImportResourceRequest
The request to import a resource.
| Field | Type | Description |
|---|---|---|
resource_type | string | |
resource_id | uuid | |
resource_address | string | |
workspace_name | string |
ReleaseLockRequest
The request to release a state lock.
| Field | Type | Description |
|---|---|---|
workspace_name | string | |
lock_id | string |
accessTokenResponse
| Field | Type | Description |
|---|---|---|
id | string | |
workspace_id | string | |
user_id | string | |
token optional | string | |
scopes | array of string | |
expires_at optional | timestamp | |
created_at | timestamp |
agentConfigBody
| Field | Type | Description |
|---|---|---|
scripts | array of Script | |
metadata | array of MetadataItem | |
apps | array of AppCheck | |
env | object of string | Write-only after save: member responses mask every value, and only the agent's own environment route delivers the values. |
env_keep optional | array of string |
agentLogPage
| Field | Type | Description |
|---|---|---|
entries | array of LogEntry | |
has_more | boolean |
authorizeBody
| Field | Type | Description |
|---|---|---|
origin | string | |
state | string |
autostartBody
A workspace's autostart schedule in a request.
| Field | Type | Description |
|---|---|---|
schedule | string | |
timezone optional | string |
buildListResponse
| Field | Type | Description |
|---|---|---|
builds | array of v1.buildResponse |
buildLogEntry
One line of a build log.
| Field | Type | Description |
|---|---|---|
sequence | integer | |
source | string | |
level | string | |
message | string | |
created_at | timestamp |
buildLogPage
| Field | Type | Description |
|---|---|---|
entries | array of v1.buildLogEntry | |
has_more | boolean | |
build_state | string |
buildResponse
| Field | Type | Description |
|---|---|---|
id | string | |
workspace_id | string | |
org_id | string | |
initiator_id | string | |
template_version_id | string | |
provisioner_job_id optional | string | |
build_number | integer | |
reason | string | |
state | string | |
desired_state | string | |
created_at | timestamp | |
updated_at | timestamp | |
completed_at optional | timestamp | |
deadline_at optional | timestamp | |
resources optional | array of BuildResource | |
failure_message optional | string | Why a failed build failed, as its provisioner job reported it. |
createAccessTokenRequest
| Field | Type | Description |
|---|---|---|
scopes | array of string | |
expires_at optional | string |
createInvitationRequest
| Field | Type | Description |
|---|---|---|
email | string | |
role | string |
createWorkspaceRequest
| Field | Type | Description |
|---|---|---|
name | string | |
template_id | string | |
template_version_id optional | string | |
parameters optional | object of string | |
ttl_seconds optional | integer | |
autostart_schedule optional | string | |
idle_timeout_seconds optional | integer | The workspace's own idle timeout (0: the organization's default), within the organization's policy. |
autostart optional | v1.autostartBody | The workspace's autostart schedule (5-field cron, IANA time zone); it replaces autostart_schedule. |
project_id optional | string | ProjectID creates the workspace in a Directory project of the organization; the caller must hold workspaces:use or workspaces:create on the project and be a member of it (or hold workspaces:manage on the organization). Without it the caller needs workspaces:create on the organization. |
environment_id optional | string | EnvironmentID names the cloud environment the workspace runs in; empty uses the default environment of Cloud workspaces, or none. An environment that starts from a template makes template_id optional. |
repository optional | string | The git repository the workspace is for (Brief H item 6): an address the repository canonical form accepts (https, ssh or scp-like; never with credentials or a query; a port is dropped), stored and answered as host/owner/name. Metadata: the template decides what is cloned. |
createWorkspaceResponse
| Field | Type | Description |
|---|---|---|
workspace | v1.workspaceResponse | |
build | v1.buildResponse |
deprecateRequest
| Field | Type | Description |
|---|---|---|
message | string |
dormancyBody
| Field | Type | Description |
|---|---|---|
enabled | boolean | |
delete_after_days | integer | |
notice_days | integer |
enableGuestAccessRequest
| Field | Type | Description |
|---|---|---|
allowed_actions | array of string | |
expires_at optional | string |
gitCredentialBody
| Field | Type | Description |
|---|---|---|
username | string | |
secret | string |
guestAccessResponse
| Field | Type | Description |
|---|---|---|
id | string | |
workspace_id | string | |
enabled | boolean | |
token | string | |
expires_at optional | timestamp | |
allowed_actions | array of string |
invitationResponse
| Field | Type | Description |
|---|---|---|
id | string | |
workspace_id | string | |
org_id | string | |
email | string | |
role | string | |
token optional | string | |
expires_at | timestamp | |
accepted_at optional | timestamp | |
created_by | string | |
created_at | timestamp |
lifecyclePolicyBody
| Field | Type | Description |
|---|---|---|
max_ttl_seconds | integer | |
default_idle_timeout_seconds | integer | |
max_idle_timeout_seconds | integer | |
dormancy | v1.dormancyBody | |
version | integer | The version the change is made on (the one a GET returned; 0 for an organization that never set a policy). |
lifecyclePolicyResponse
| Field | Type | Description |
|---|---|---|
org_id | string | |
updated_at | timestamp | |
updated_by optional | string | |
max_ttl_seconds | integer | |
default_idle_timeout_seconds | integer | |
max_idle_timeout_seconds | integer | |
dormancy | v1.dormancyBody | |
version | integer | The version the change is made on (the one a GET returned; 0 for an organization that never set a policy). |
patchAutostart
The autostart field of an update, which tells an absent field from a null one: null clears the schedule.
| Field | Type | Description |
|---|---|---|
schedule | string | |
timezone optional | string |
permissionResponse
| Field | Type | Description |
|---|---|---|
user_id | string | |
workspace_id | string | |
role | string | |
can_view | boolean | |
can_terminal | boolean | |
can_edit | boolean | |
can_start | boolean | |
can_stop | boolean | |
can_delete | boolean |
putWorkspacePolicyRequest
| Field | Type | Description |
|---|---|---|
ide_allowlist | JSON | |
ssh_certificates_enabled optional | boolean | |
ssh_registered_key_fallback optional | boolean | |
web_editor optional | boolean | |
app_max_share optional | string |
rebuildWorkspaceRequest
| Field | Type | Description |
|---|---|---|
template_version_id optional | string | |
parameters optional | object of string |
setAccessRequest
| Field | Type | Description |
|---|---|---|
access | string |
setPermissionRequest
| Field | Type | Description |
|---|---|---|
subject_id | string | |
subject_type | string | "user" or "group" |
role | string | "use" |
setShareBody
| Field | Type | Description |
|---|---|---|
share | string |
shareResponse
| Field | Type | Description |
|---|---|---|
id | string | |
workspace_id | string | |
org_id | string | |
shared_with | string | |
role | string | |
expires_at optional | timestamp | |
created_by | string | |
created_at | timestamp |
shareWorkspaceRequest
| Field | Type | Description |
|---|---|---|
shared_with | string | User ID |
role | string | |
expires_at optional | string |
sshCertificateRequest
| Field | Type | Description |
|---|---|---|
public_key | string |
templatesCreateTemplateRequest
| Field | Type | Description |
|---|---|---|
name | string | |
description | string | |
icon | string | |
access | string | |
builtin | string | |
version_name | string | |
version_message | string |
terminalAvailability
What the console shows: whether the person can open a terminal in the workspace now, and if not, why.
| Field | Type | Description |
|---|---|---|
available | boolean | |
reason optional | string | |
message optional | string | |
max_session_seconds | integer | MaxSessionSeconds and IdleTimeoutSeconds are the server's limits. |
idle_timeout_seconds | integer |
terminalTicketBody
| Field | Type | Description |
|---|---|---|
session_id optional | string | SessionID reattaches a terminal session of the caller that is still running. |
origin optional | string | Origin binds the ticket to one terminal origin (one of NI_AUTH_TERMINAL_ORIGINS): the WebSocket is then accepted from that origin only. Without it, from any terminal origin. |
updateTemplateRequest
| Field | Type | Description |
|---|---|---|
name optional | string | |
description optional | string | |
icon optional | string |
updateWorkspaceRequest
| Field | Type | Description |
|---|---|---|
name optional | string | |
ttl_seconds optional | integer | |
idle_timeout_seconds optional | integer | |
autostart_schedule optional | string | |
autostart optional | v1.patchAutostart | Autostart sets the schedule and its time zone; "autostart": null clears it. |
workspaceListResponse
| Field | Type | Description |
|---|---|---|
workspaces | array of v1.workspaceResponse | |
next_cursor | string |
workspaceResponse
| Field | Type | Description |
|---|---|---|
id | string | |
org_id | string | |
owner_id | string | |
template_id | string | |
active_version_id optional | string | |
project_id optional | string | The Directory project of the workspace, null for an account-level one. |
repository optional | string | The canonical git repository the workspace is for (host/owner/name), omitted when none was named. |
name | string | |
ttl_seconds | integer | |
autostart_schedule optional | string | |
idle_timeout_seconds | integer | The workspace's own idle timeout (0: the organization's default). |
autostart optional | Autostart | The schedule and its time zone, null when none is set. |
status | string | |
health | string | |
agent_connected | boolean | |
status_message optional | string | |
created_at | timestamp | |
updated_at | timestamp | |
deleted_at optional | timestamp | |
last_used_at optional | timestamp | |
nrn optional | string | The workspace's resource name, set on every response. |
runtime optional | Runtime | The runtime the workspace runs on, decided from the compute resource its provider recorded for its latest build ("Not recorded" when none did). Set by get and list. |
cost optional | Cost | What the workspace's running time cost at list price, from the billing usage ledger, in total and this month. Set by get and list. |
lifecycle optional | LifecycleView | What the server decided about the workspace's stop, start and dormancy: the effective settings under the organization's policy, the last activity, when it stops next and unless-active, when its schedule starts it, its dormancy countdown and the p50 and p95 of the time its agent took to connect. Set by get and list. |
idle_basis optional | string | Lifecycle.idle_basis, also on the workspace itself: "server_traffic_only" when its agent reports no activity (the idle timeout is then at least 4 hours), else "agent_reported". |
Autostart
A workspace's autostart schedule: Schedule is a 5-field cron expression and Timezone the IANA zone it is evaluated in (UTC when empty).
| Field | Type | Description |
|---|---|---|
schedule | string | |
timezone | string |
BuildResource
An infrastructure resource reported by the provisioner upon job completion.
| Field | Type | Description |
|---|---|---|
external_id | string | |
type | string | "container", "pod", "volume", … |
name | string | |
workspace_id | uuid | |
agent_path optional | string | |
metadata optional | object of string |
DormancyView
The countdown of a stopped workspace in an organization that deletes dormant workspaces.
| Field | Type | Description |
|---|---|---|
enabled | boolean | |
stopped_since | timestamp | |
delete_at optional | timestamp | |
notices_sent | integer |
LifecycleView
What the workspace page shows of a workspace's lifecycle, decided on the server: the console renders it and computes nothing.
| Field | Type | Description |
|---|---|---|
effective_ttl_seconds | integer | |
effective_idle_timeout_seconds | integer | |
last_activity_at optional | timestamp | |
last_activity_source | string | |
next_stop optional | NextStopView | |
next_start optional | NextStartView | |
dormancy optional | DormancyView | |
ready_seconds optional | ReadyStats | |
idle_basis | string | "server_traffic_only" when the agent has not reported activity since the workspace started (the idle timeout is then at least 4 hours) and "agent_reported" otherwise. |
NextStartView
When a stopped workspace's schedule next starts it.
| Field | Type | Description |
|---|---|---|
at | timestamp | |
timezone | string |
NextStopView
When a running workspace stops: UnlessActive is true for the idle stop, which activity postpones, false for the maximum runtime.
| Field | Type | Description |
|---|---|---|
reason | string | |
at | timestamp | |
in_seconds | integer | |
unless_active | boolean |
ReadyStats
The percentiles of workspace_ready_seconds.
| Field | Type | Description |
|---|---|---|
p50 | number | |
p95 | number | |
samples | integer | |
scope | string | "workspace" when the workspace has enough samples of its own, else "org". |
This page is generated from the server's route table and the Go handlers that serve each route. Do not edit it by hand.