API by area

Workspaces

122 endpoints. Paths are relative to https://api.sandscale.dev; values in braces are ones you fill in.

API reference · Authentication · Errors

MethodPathWhat it does
GET/api/v1/cloud-environmentsList cloud environments
POST/api/v1/cloud-environmentsCreate 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/placementList placement
PUT/api/v1/cloud-environments/placementReplaces 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/resolveAnswers which environment a session of a product would start with for the caller:
GET/api/v1/cloud-environments/settingsList settings
PUT/api/v1/cloud-environments/settings/self-hostedSet self hosted
GET/api/v1/environmentsList environments
POST/api/v1/environmentsCreate an environment
GET/api/v1/environments/{id}Get one environment
PUT/api/v1/environments/{id}/rulesSet the rules of an environment
POST/api/v1/environments/{id}/sessionsCreate a session for an environment
POST/api/v1/environments/evaluateCreate an evaluate
POST/api/v1/gpu/allocateCreate an allocate
GET/api/v1/gpu/nodesList nodes
POST/api/v1/gpu/nodesCreate a node
POST/api/v1/gpu/nodes/{id}/drainDrain a node
POST/api/v1/gpu/scheduleCreate a schedule
GET/api/v1/gpu/utilizationList utilization
POST/api/v1/orgs/{id}/custom-domainCustom domain an org
DELETE/api/v1/orgs/{id}/custom-domainDelete the custom domain of an org
POST/api/v1/orgs/{id}/custom-domain/verifyCreate a verify
PUT/api/v1/orgs/{orgID}/custom-domainKeeps 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}/subdomainUpdates an organization's subdomain
GET/api/v1/orgs/{orgID}/templatesList the templates of an org
POST/api/v1/orgs/{orgID}/templatesMakes 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}/accessAccess of a template
PUT/api/v1/orgs/{orgID}/templates/{id}/accessSet the access of a template
POST/api/v1/orgs/{orgID}/templates/{id}/deprecateDeprecate a template
GET/api/v1/orgs/{orgID}/templates/{id}/launchAnswers 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}/permissionsList the permissions of a template
PUT/api/v1/orgs/{orgID}/templates/{id}/permissionsSet the permissions of a template
DELETE/api/v1/orgs/{orgID}/templates/{id}/permissions/{subjectID}Delete one permission
GET/api/v1/orgs/{orgID}/templates/{id}/statsStats of a template
POST/api/v1/orgs/{orgID}/templates/{id}/undeprecateUndeprecate a template
GET/api/v1/orgs/{orgID}/templates/{id}/versionsList the versions of a template
POST/api/v1/orgs/{orgID}/templates/{id}/versionsTakes 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}/activateActivate a version
GET/api/v1/orgs/{orgID}/templates/{id}/versions/{vid}/archiveArchive of a version
GET/api/v1/orgs/{orgID}/templates/{id}/versions/{vid}/parametersList the parameters of a version
GET/api/v1/orgs/{orgID}/templates/builtinsList 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/importImports an existing resource.
GET/api/v1/orgs/{orgID}/terraform/importsLists 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}/forceForceUnlock forcibly releases a lock (admin operation).
GET/api/v1/orgs/{orgID}/terraform/operationsLists operations for a workspace.
GET/api/v1/orgs/{orgID}/terraform/plansLists plans for a workspace.
POST/api/v1/orgs/{orgID}/terraform/plansCreates 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}/applyMarks a plan as applied.
GET/api/v1/orgs/{orgID}/terraform/resourcesLists Terraform-managed resources.
GET/api/v1/orgs/{orgID}/terraform/resources/{resourceID}Retrieves a resource by ID.
POST/api/v1/orgs/{orgID}/terraform/resources/{resourceID}/taintMarks a resource as tainted.
DELETE/api/v1/orgs/{orgID}/terraform/resources/{resourceID}/taintRemoves 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}/versionsLists historical state versions.
DELETE/api/v1/orgs/{orgID}/tokens/{tokenID}Delete one token
POST/api/v1/orgs/{orgID}/workspaceapps/authorizeFor 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}/workspacesList the workspaces of an org
POST/api/v1/orgs/{orgID}/workspacesCreate a workspace for an org
GET/api/v1/orgs/{orgID}/workspaces/{id}/metricsList the metrics of a workspace
GET/api/v1/orgs/{orgID}/workspaces/{id}/metrics/dashboardList dashboard
GET/api/v1/orgs/{orgID}/workspaces/{id}/metrics/definitionsList definitions
GET/api/v1/orgs/{orgID}/workspaces/{id}/metrics/latestList 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}/agentThe agent and its latest stats, metadata and app health.
GET/api/v1/orgs/{orgID}/workspaces/{wsID}/agent/configEnvironment 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/configThe 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/logsHandles GET .../agent/logs?after=&limit=.
GET/api/v1/orgs/{orgID}/workspaces/{wsID}/agent/logs/streamHandles 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}/appsFor callers holding workspaces:use on the workspace.
PATCH/api/v1/orgs/{orgID}/workspaces/{wsID}/apps/{slug}/shareThe 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}/buildsList 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}/logsHandles GET .../builds/{buildID}/logs?after=&limit=.
GET/api/v1/orgs/{orgID}/workspaces/{wsID}/builds/{buildID}/logs/streamHandles 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}/connectWhat 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-credentialsSecrets 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}/guestGuest a workspace
DELETE/api/v1/orgs/{orgID}/workspaces/{wsID}/guestDelete the guest of a workspace
GET/api/v1/orgs/{orgID}/workspaces/{wsID}/invitationsList the invitations of a workspace
POST/api/v1/orgs/{orgID}/workspaces/{wsID}/inviteInvite a workspace
GET/api/v1/orgs/{orgID}/workspaces/{wsID}/openThe 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}/permissionsList the permissions of a workspace
GET/api/v1/orgs/{orgID}/workspaces/{wsID}/ptyA 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}/rebuildRebuild a workspace
POST/api/v1/orgs/{orgID}/workspaces/{wsID}/shareShare a workspace
GET/api/v1/orgs/{orgID}/workspaces/{wsID}/sharesList the shares of a workspace
GET/api/v1/orgs/{orgID}/workspaces/{wsID}/sshAn 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/certificateA 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}/startStart a workspace
POST/api/v1/orgs/{orgID}/workspaces/{wsID}/stopStop a workspace
GET/api/v1/orgs/{orgID}/workspaces/{wsID}/terminalThe 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/availabilityWhether 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/ticketsA 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}/tokensList the tokens of a workspace
POST/api/v1/orgs/{orgID}/workspaces/{wsID}/tokensCreate a token for a workspace
GET/api/v1/orgs/{orgID}/workspaces/lifecycle-policyList lifecycle policy
PUT/api/v1/orgs/{orgID}/workspaces/lifecycle-policySet lifecycle policy
GET/api/v1/orgs/{orgID}/workspaces/policyList policy
PUT/api/v1/orgs/{orgID}/workspaces/policyFields 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-caPhase 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/resolveResolves 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

Permission
cloud.environments.settings:manage
Path parameters
product
Request body
object
Response
200: Settings
Errors
400: invalid_json; 401: unauthorized; 415: content_type; 503: environments_not_configured

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

Permission
cloud.environments.settings:manage
Request body
object
Response
200: Settings
Errors
400: invalid_allow, invalid_json; 401: unauthorized; 415: content_type; 503: environments_not_configured

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

Permission
compute:admin
Request body
GPUNode
Response
201: GPUNode
Errors
400: invalid_json, invalid_request; 401: unauthorized; 404: not_found; 409: no_capacity; 415: content_type

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

Permission
api:access
Request body
GPUJob
Response
201: GPUJob
Errors
400: invalid_json, invalid_request; 401: unauthorized; 404: not_found; 409: no_capacity; 415: content_type

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

FieldTypeDescription
productstring
environment_idstring

object

FieldTypeDescription
project_id optionalstring
namestring
custom_namestring
rules optionalEnvironmentRules

object

FieldTypeDescription
session_idstring
modelstring
operationstring
cost_so_farnumber

object

FieldTypeDescription
session_idstring
agent_idstring
user_id optionalstring

object

FieldTypeDescription
domainstring

object

FieldTypeDescription
reasonstring

object

FieldTypeDescription
hoststring

object

FieldTypeDescription
environment_id optionalstring

object

FieldTypeDescription
allowedarray of string
preferredstring

object

FieldTypeDescription
allow optionalboolean

object

FieldTypeDescription
custom_domain optionalstring

object

FieldTypeDescription
subdomain optionalstring

AppCheck

A workspace app whose health the agent checks.

FieldTypeDescription
slugstring
urlstringWhere the app serves inside the workspace (loopback only).
health_url optionalstringPolled 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.

FieldTypeDescription
hoststring
usernamestring
updated_byuuid
updated_attimestamp

LogEntry

One shipped log line.

FieldTypeDescription
idinteger
sourcestring
levelstring
messagestring
logged_attimestamp

MetadataItem

A script whose output the agent reports under Key.

FieldTypeDescription
keystring
scriptstring
interval_seconds optionalinteger
timeout_seconds optionalinteger

Script

A lifecycle script.

FieldTypeDescription
namestring
commandstringRun with /bin/sh -c as the workspace user.
run_onstring"startup", "shutdown" or "cron".
cron optionalstring"@every <duration>" for cron scripts (at least one minute).
timeout_seconds optionalintegerTimeoutSeconds bounds one run; 0 means the default of ten minutes.
required optionalbooleanRequired 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.

FieldTypeDescription
idstring
namestring
statusstring
providerstringAws or azure; AccountID is the AWS account or Azure subscription; Region is the provider's region.
account_idstring
regionstring

ComputeSourceOption

One compute source choice: available or why not.

FieldTypeDescription
sourcestring
namestring
descriptionstring
availableboolean
reason optionalstring
connections optionalarray of BYOCConnection

EnvVar

A non-secret environment variable.

FieldTypeDescription
namestring
valuestring

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.

FieldTypeDescription
idstring
nrn optionalstring
namestring
descriptionstring
compute_sourcestring
byoc_connection_id optionalstring
template_kind optionalstring
template_id optionalstring
size optionalstring
network_accessstring
allowed_domainsarray of string
include_trustedboolean
setup_scriptstring
env_varsarray of EnvVar
secret_refsarray of SecretRef
accessstring
statusstring
status_message optionalstring
revisioninteger
last_activity_at optionaltimestamp
used_byarray of string
created_by optionalstring
updated_by optionalstring
created_attimestamp
updated_attimestamp
can_editbooleanCanEdit and CanManage are the caller's own access, decided by access control, so the console shows only the actions the server will accept.
can_manageboolean

Input

FieldTypeDescription
name optionalstring
description optionalstring
compute_source optionalstring
byoc_connection_id optionalstring
template_kind optionalstring
template_id optionalstring
size optionalstring
network_access optionalstring
allowed_domains optionalarray of string
include_trusted optionalboolean
setup_script optionalstring
env_text optionalstringThe "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 optionalarray of EnvVar
secret_refs optionalarray of SecretRef
access optionalstring
revision optionalintegerRevision, 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.

FieldTypeDescription
environmentsarray of Environment
usablearray of Summary

NetworkOption

One network access choice, as the console offers it.

FieldTypeDescription
accessstring
namestring
descriptionstring
recommended optionalboolean

PlacementSettings

The page model of Settings > Compute: the server's rules and the account's policy.

FieldTypeDescription
planstring
regulatedboolean
policyPolicy
targetsarray of PlacementTarget
operator_default optionalstring
can_manageboolean
notesarray of stringSentences the server wants shown (the regulated restriction).

PlacementTarget

One place compute can run, as the console shows it.

FieldTypeDescription
targetstring
labelstring
availableboolean
reason optionalstringReason says why the account cannot use it.
allowedboolean
capabilitiesCapabilities

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.

FieldTypeDescription
productstring
namestring
descriptionstring
environment optionalSummary
fallbackstringFallback 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.

FieldTypeDescription
codestring
valueinteger
usageinteger

Resolution

What a session of a product would start with for a principal: the environment (nil: the product's built-in behaviour) and why.

FieldTypeDescription
productstring
environment optionalSummary
sourcestring"requested" (the caller named it), "default" (the product's default) or "builtin" (neither: the product's built-in behaviour, described by Fallback).
fallback optionalstring

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.

FieldTypeDescription
namestring
pathstring
fieldstring

Settings

The page model of Cloud environments for administrators: everything the console renders around the list.

FieldTypeDescription
allow_self_hostedboolean
updated_at optionaltimestamp
updated_by optionalstring
defaultsarray of ProductDefault
trustedTrustedList
sizesarray of Size
network_optionsarray of NetworkOption
compute_sourcesarray of ComputeSourceOption
quotaQuotaView
regionstring
can_manageboolean
can_createboolean

Size

A size the server offers.

FieldTypeDescription
keystring
namestring
cpu_coresinteger
memory_gbinteger
disk_gbinteger

Summary

An environment as a list shows it to a caller who may only use it: no setup script, variables or references.

FieldTypeDescription
idstring
nrn optionalstring
namestring
descriptionstring
compute_sourcestring
network_accessstring
size optionalstring
accessstring
statusstring
status_message optionalstring
last_activity_at optionaltimestamp
used_byarray of string

TrustedList

The trusted network list, read-only.

FieldTypeDescription
versionstring
groupsarray 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.

FieldTypeDescription
gpubooleanGPU: the provider can schedule GPU compute.
nested_isolationbooleanNestedIsolation: workloads can run in a nested isolation layer (microVMs or gVisor sandboxes inside the instance), which Sandscale sandboxes need.
snapshotsbooleanSnapshots: Snapshot and Restore work.
logsbooleanLogs: Logs works.
persistent_storagebooleanPersistentStorage: a stopped instance's storage survives.
max_vcpuintegerMaxVCPU and MaxMemoryGB bound one instance.
max_memory_gbinteger
regions optionalarray of stringThe 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).

FieldTypeDescription
totalMoney
this_monthMoney

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.

FieldTypeDescription
usdstring
displaystring

Runtime

The runtime a sandbox or workspace ran on.

FieldTypeDescription
kindstringFirecracker, docker_gvisor, docker, kubernetes, gvisor (a gVisor container whose runtime was not recorded) or not_recorded.
labelstringThe 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.

FieldTypeDescription
keystring
namestring
domainsarray of string

EnvironmentRules

EnvironmentRules defines the governance constraints for an environment.

FieldTypeDescription
require_hitlboolean
allowed_modelsarray of string
blocked_modelsarray of string
max_cost_per_session_usdnumber
max_budget_per_day_usdnumber
allow_agent_writeboolean
allow_bash_execboolean
require_approval_for_writeboolean
allowed_tool_scopesarray of string
data_class_restrictionsarray of string

GPUAllocation

GPUAllocation reserves GPU slots on a node for a team, following the available → reserved → in-use → released state machine.

FieldTypeDescription
idstring
node_idstring
team_idstring
gpu_slotsinteger
priorityinteger
statestring
expires_at optionaltimestamp
created_attimestamp
updated_attimestamp

GPUJob

GPUJob represents a unit of work scheduled to run on a GPU node. Status lifecycle: queued → running → (completed | failed | cancelled).

FieldTypeDescription
idstring
org_idstring
node_idstring
model_idstring
statusstring
gpus_neededinteger
priorityinteger
queued_attimestamp
started_at optionaltimestamp
finished_at optionaltimestamp

GPUNode

GPUNode represents a physical or virtual machine hosting one or more GPUs.

FieldTypeDescription
idstring
org_idstring
hostnamestring
gpu_typestring
gpu_countinteger
vram_per_gpu_gbinteger
driver_versionstring
cuda_versionstring
statusstring
labels optionalobject of string
created_attimestamp
updated_attimestamp

Domain

An Organization's custom domain as the API shows it.

FieldTypeDescription
idstring
org_idstring
domainstring
statusstring
verifiedboolean
verified_at optionaltimestamp
dns_recordsarray of Record
issuer optionalstring
last_checked_at optionaltimestamp
last_check_result optionalstring
failed_checksinteger
dns_error_since optionaltimestampWhen the run of DNS errors on every check began (none: the last check got an answer).
disabled_at optionaltimestamp
disabled_reason optionalstring
tls_provisionedbooleanTLSProvisioned: the TLS edge asked for, and was allowed, a certificate for the domain.
created_attimestamp
updated_attimestamp
verification_tokenstringThe 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.

FieldTypeDescription
typestring
namestring
valuestring
purposestringPurpose says what the record proves: ownership or routing.

Policy

The organization's own placement policy. The zero value places anywhere the rules allow.

FieldTypeDescription
allowedarray of stringThe targets the organization permits; empty means every target the rules allow.
preferred optionalstringTried first when it is allowed and eligible.

PortalContext

PortalContext holds resolved portal information

FieldTypeDescription
portal_typestring
org_id optionaluuid
org_name optionalstring
org_slug optionalstring
bu_id optionaluuid
bu_name optionalstring
branding_id optionalstringResolved branding config
hoststring

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.

FieldTypeDescription
existsboolean
portal_typestring
org_slug optionalstring
hoststring

AccessView

Who may use a template, for a caller who manages templates.

FieldTypeDescription
accessstring
access_labelstring
grantsarray of Grant
grants_applybooleanGrantsApply says whether the grants count under the current mode.
modesarray of ModeOption

Grant

One explicit grant as the access panel shows it.

FieldTypeDescription
subject_typestring
subject_iduuid
namestringThe 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).
currentboolean
rolestring
granted_byuuid
granted_attimestamp

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.

FieldTypeDescription
namestring
display_namestring
descriptionstring
typestring
requiredboolean
sensitiveboolean
default optionalstring
choices optionalarray of string
min optionalnumber
max optionalnumber
pattern optionalstring
size optionalstring"cpu_cores" or "memory_gb" for a size parameter, else "".
unit optionalstring

LaunchView

What the new-workspace form shows for a template.

FieldTypeDescription
templateSummary
versionVersionRef
parametersarray of LaunchParameter
sizesSizes
size_limitsSizeLimits

List

The template list for one caller.

FieldTypeDescription
templatesarray of Summary
next_cursorstring
can_manageboolean
size_limitsSizeLimits

ModeOption

An access mode with Sandscale's label for it.

FieldTypeDescription
valuestring
labelstring

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.

FieldTypeDescription
max_cpu_coresnumber
max_memory_gbnumber

SizeOffer

What one size parameter of a version lets a member choose, within the deployment's maximum.

FieldTypeDescription
parameterstring
options optionalarray of string
min optionalnumber
maxnumber
default optionalstring
unitstring

Sizes

What a version offers for workspace sizes, with a label Sandscale writes for people (the console shows it as is).

FieldTypeDescription
cpu_cores optionalSizeOffer
memory_gb optionalSizeOffer
labelstring

Summary

One template as the list and the detail page show it.

FieldTypeDescription
iduuid
org_iduuid
namestring
descriptionstring
iconstringURL or empty
active_version_id optionaluuid
created_byuuid
created_attimestamp
updated_attimestamp
deleted_at optionaltimestamp
accessstringAccess says who may create workspaces from the template.
deprecated_at optionaltimestampSet while the template is deprecated: it creates no new workspace; existing workspaces keep running.
deprecated_by optionaluuid
deprecation_message optionalstring
builtin optionalstringThe key of the built-in template it was created from, or "".
updated_by optionaluuid
nrn optionalstringThe template's NRN; the API handler sets it from the owning organization's Account ID and the cell.
statusstring
status_labelstring
access_labelstring
versionsinteger
active_version optionalVersionRef
sizesSizes
can_usebooleanCanUse says whether the caller may create a workspace from it now (not deprecated, deleted or without a version, and allowed).
can_managebooleanCanManage says whether the caller may change it.

VersionRef

VersionRef names a version.

FieldTypeDescription
iduuid
namestring

AcquireLockRequest

The request to acquire a state lock.

FieldTypeDescription
workspace_namestring
lock_idstring
operationstring
whostring
version optionalstring
path optionalstring
info optionalstring
ttl optionalintegerSeconds

CreatePlanRequest

The request to create a plan.

FieldTypeDescription
workspace_namestring
plan_jsonJSON
terraform_versionstring
ttl optionalintegerSeconds

ImportResourceRequest

The request to import a resource.

FieldTypeDescription
resource_typestring
resource_iduuid
resource_addressstring
workspace_namestring

ReleaseLockRequest

The request to release a state lock.

FieldTypeDescription
workspace_namestring
lock_idstring

accessTokenResponse

FieldTypeDescription
idstring
workspace_idstring
user_idstring
token optionalstring
scopesarray of string
expires_at optionaltimestamp
created_attimestamp

agentConfigBody

FieldTypeDescription
scriptsarray of Script
metadataarray of MetadataItem
appsarray of AppCheck
envobject of stringWrite-only after save: member responses mask every value, and only the agent's own environment route delivers the values.
env_keep optionalarray of string

agentLogPage

FieldTypeDescription
entriesarray of LogEntry
has_moreboolean

authorizeBody

FieldTypeDescription
originstring
statestring

autostartBody

A workspace's autostart schedule in a request.

FieldTypeDescription
schedulestring
timezone optionalstring

buildListResponse

FieldTypeDescription
buildsarray of v1.buildResponse

buildLogEntry

One line of a build log.

FieldTypeDescription
sequenceinteger
sourcestring
levelstring
messagestring
created_attimestamp

buildLogPage

FieldTypeDescription
entriesarray of v1.buildLogEntry
has_moreboolean
build_statestring

buildResponse

FieldTypeDescription
idstring
workspace_idstring
org_idstring
initiator_idstring
template_version_idstring
provisioner_job_id optionalstring
build_numberinteger
reasonstring
statestring
desired_statestring
created_attimestamp
updated_attimestamp
completed_at optionaltimestamp
deadline_at optionaltimestamp
resources optionalarray of BuildResource
failure_message optionalstringWhy a failed build failed, as its provisioner job reported it.

createAccessTokenRequest

FieldTypeDescription
scopesarray of string
expires_at optionalstring

createInvitationRequest

FieldTypeDescription
emailstring
rolestring

createWorkspaceRequest

FieldTypeDescription
namestring
template_idstring
template_version_id optionalstring
parameters optionalobject of string
ttl_seconds optionalinteger
autostart_schedule optionalstring
idle_timeout_seconds optionalintegerThe workspace's own idle timeout (0: the organization's default), within the organization's policy.
autostart optionalv1.autostartBodyThe workspace's autostart schedule (5-field cron, IANA time zone); it replaces autostart_schedule.
project_id optionalstringProjectID 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 optionalstringEnvironmentID 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 optionalstringThe 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

FieldTypeDescription
workspacev1.workspaceResponse
buildv1.buildResponse

deprecateRequest

FieldTypeDescription
messagestring

dormancyBody

FieldTypeDescription
enabledboolean
delete_after_daysinteger
notice_daysinteger

enableGuestAccessRequest

FieldTypeDescription
allowed_actionsarray of string
expires_at optionalstring

gitCredentialBody

FieldTypeDescription
usernamestring
secretstring

guestAccessResponse

FieldTypeDescription
idstring
workspace_idstring
enabledboolean
tokenstring
expires_at optionaltimestamp
allowed_actionsarray of string

invitationResponse

FieldTypeDescription
idstring
workspace_idstring
org_idstring
emailstring
rolestring
token optionalstring
expires_attimestamp
accepted_at optionaltimestamp
created_bystring
created_attimestamp

lifecyclePolicyBody

FieldTypeDescription
max_ttl_secondsinteger
default_idle_timeout_secondsinteger
max_idle_timeout_secondsinteger
dormancyv1.dormancyBody
versionintegerThe version the change is made on (the one a GET returned; 0 for an organization that never set a policy).

lifecyclePolicyResponse

FieldTypeDescription
org_idstring
updated_attimestamp
updated_by optionalstring
max_ttl_secondsinteger
default_idle_timeout_secondsinteger
max_idle_timeout_secondsinteger
dormancyv1.dormancyBody
versionintegerThe 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.

FieldTypeDescription
schedulestring
timezone optionalstring

permissionResponse

FieldTypeDescription
user_idstring
workspace_idstring
rolestring
can_viewboolean
can_terminalboolean
can_editboolean
can_startboolean
can_stopboolean
can_deleteboolean

putWorkspacePolicyRequest

FieldTypeDescription
ide_allowlistJSON
ssh_certificates_enabled optionalboolean
ssh_registered_key_fallback optionalboolean
web_editor optionalboolean
app_max_share optionalstring

rebuildWorkspaceRequest

FieldTypeDescription
template_version_id optionalstring
parameters optionalobject of string

setAccessRequest

FieldTypeDescription
accessstring

setPermissionRequest

FieldTypeDescription
subject_idstring
subject_typestring"user" or "group"
rolestring"use"

setShareBody

FieldTypeDescription
sharestring

shareResponse

FieldTypeDescription
idstring
workspace_idstring
org_idstring
shared_withstring
rolestring
expires_at optionaltimestamp
created_bystring
created_attimestamp

shareWorkspaceRequest

FieldTypeDescription
shared_withstringUser ID
rolestring
expires_at optionalstring

sshCertificateRequest

FieldTypeDescription
public_keystring

templatesCreateTemplateRequest

FieldTypeDescription
namestring
descriptionstring
iconstring
accessstring
builtinstring
version_namestring
version_messagestring

terminalAvailability

What the console shows: whether the person can open a terminal in the workspace now, and if not, why.

FieldTypeDescription
availableboolean
reason optionalstring
message optionalstring
max_session_secondsintegerMaxSessionSeconds and IdleTimeoutSeconds are the server's limits.
idle_timeout_secondsinteger

terminalTicketBody

FieldTypeDescription
session_id optionalstringSessionID reattaches a terminal session of the caller that is still running.
origin optionalstringOrigin 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

FieldTypeDescription
name optionalstring
description optionalstring
icon optionalstring

updateWorkspaceRequest

FieldTypeDescription
name optionalstring
ttl_seconds optionalinteger
idle_timeout_seconds optionalinteger
autostart_schedule optionalstring
autostart optionalv1.patchAutostartAutostart sets the schedule and its time zone; "autostart": null clears it.

workspaceListResponse

FieldTypeDescription
workspacesarray of v1.workspaceResponse
next_cursorstring

workspaceResponse

FieldTypeDescription
idstring
org_idstring
owner_idstring
template_idstring
active_version_id optionalstring
project_id optionalstringThe Directory project of the workspace, null for an account-level one.
repository optionalstringThe canonical git repository the workspace is for (host/owner/name), omitted when none was named.
namestring
ttl_secondsinteger
autostart_schedule optionalstring
idle_timeout_secondsintegerThe workspace's own idle timeout (0: the organization's default).
autostart optionalAutostartThe schedule and its time zone, null when none is set.
statusstring
healthstring
agent_connectedboolean
status_message optionalstring
created_attimestamp
updated_attimestamp
deleted_at optionaltimestamp
last_used_at optionaltimestamp
nrn optionalstringThe workspace's resource name, set on every response.
runtime optionalRuntimeThe 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 optionalCostWhat 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 optionalLifecycleViewWhat 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 optionalstringLifecycle.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).

FieldTypeDescription
schedulestring
timezonestring

BuildResource

An infrastructure resource reported by the provisioner upon job completion.

FieldTypeDescription
external_idstring
typestring"container", "pod", "volume", …
namestring
workspace_iduuid
agent_path optionalstring
metadata optionalobject of string

DormancyView

The countdown of a stopped workspace in an organization that deletes dormant workspaces.

FieldTypeDescription
enabledboolean
stopped_sincetimestamp
delete_at optionaltimestamp
notices_sentinteger

LifecycleView

What the workspace page shows of a workspace's lifecycle, decided on the server: the console renders it and computes nothing.

FieldTypeDescription
effective_ttl_secondsinteger
effective_idle_timeout_secondsinteger
last_activity_at optionaltimestamp
last_activity_sourcestring
next_stop optionalNextStopView
next_start optionalNextStartView
dormancy optionalDormancyView
ready_seconds optionalReadyStats
idle_basisstring"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.

FieldTypeDescription
attimestamp
timezonestring

NextStopView

When a running workspace stops: UnlessActive is true for the idle stop, which activity postpones, false for the maximum runtime.

FieldTypeDescription
reasonstring
attimestamp
in_secondsinteger
unless_activeboolean

ReadyStats

The percentiles of workspace_ready_seconds.

FieldTypeDescription
p50number
p95number
samplesinteger
scopestring"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.