API by area

Build hosts and lab hosts

48 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/orgs/{orgID}/build/device-policiesList device policies
PUT/api/v1/orgs/{orgID}/build/device-policies/{class}Replace one device policy
GET/api/v1/orgs/{orgID}/build/devicesList devices
GET/api/v1/orgs/{orgID}/build/lab-hostsList lab hosts
GET/api/v1/orgs/{orgID}/build/lab-hosts/{hostID}Get one lab host
PATCH/api/v1/orgs/{orgID}/build/lab-hosts/{hostID}Update one lab host
GET/api/v1/orgs/{orgID}/build/lab-hosts/{hostID}/devicesList the devices of a lab host
POST/api/v1/orgs/{orgID}/build/lab-hosts/{hostID}/release-claimsHandles POST .../lab-hosts/{hostID}/release-claims (workspaces:admin, {"reason"}): releases the device claims a revoked host keeps until it confirms its teardown.
POST/api/v1/orgs/{orgID}/build/lab-hosts/{hostID}/revokeRevoke a lab host
GET/api/v1/orgs/{orgID}/build/lab-hosts/enrolment-tokensList enrolment tokens
POST/api/v1/orgs/{orgID}/build/lab-hosts/enrolment-tokensCreate an enrolment token
DELETE/api/v1/orgs/{orgID}/build/lab-hosts/enrolment-tokens/{tokenID}Delete one enrolment token
GET/api/v1/orgs/{orgID}/build/leasesList leases
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}Get one lease
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/artifactsList the artifacts of a lease
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/artifactsCreate an artifact for a lease
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts/{artifactID}Get one artifact
DELETE/api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts/{artifactID}Delete one artifact
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts/{artifactID}/contentContent of an artifact
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/cachesList the caches of a lease
PUT/api/v1/orgs/{orgID}/build/leases/{leaseID}/caches/{cacheName}/entriesSet the entries of a cach
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/caches/{cacheName}/restoreRestore of a cach
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/killKill a lease
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/releaseRelease a lease
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/renewRenew a lease
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/runsList the runs of a lease
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/runsCreate a run for a lease
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}Get one run
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}/completeComplete a run
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}/logLog of a run
PUT/api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}/logSet the log of a run
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/sshAn SSH connection to a lab lease's host as binary WebSocket messages, for the holder in their own session while the lease is active and ready and the kill switch is off. The host must hold its relay connection to this replica (503 host_not_connected otherwise). The open and the end are audited (build.lease.ssh_relay); the caller's session, permission and the lease are checked again while the connection lasts.
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/ssh/certificateCreate a certificate
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/syncSync a lease
GET/api/v1/orgs/{orgID}/build/login-wipesAnswers the organization's owed login wipes to an administrator (audited).
GET/api/v1/orgs/{orgID}/build/poolsList pools
POST/api/v1/orgs/{orgID}/build/poolsCreate a pool
GET/api/v1/orgs/{orgID}/build/pools/{poolID}Get one pool
PATCH/api/v1/orgs/{orgID}/build/pools/{poolID}Update one pool
DELETE/api/v1/orgs/{orgID}/build/pools/{poolID}Delete one pool
GET/api/v1/orgs/{orgID}/build/pools/{poolID}/cachesList the caches of a pool
DELETE/api/v1/orgs/{orgID}/build/pools/{poolID}/caches/{cacheName}Delete one cach
GET/api/v1/orgs/{orgID}/build/pools/{poolID}/enginesList the engines of a pool
POST/api/v1/orgs/{orgID}/build/pools/{poolID}/leasesCreate a lease for a pool
GET/api/v1/orgs/{orgID}/build/quotasList quotas
PUT/api/v1/orgs/{orgID}/build/quotasSet quotas
GET/api/v1/orgs/{orgID}/build/task-enginesList task engines
GET/api/v1/orgs/{orgID}/build/usageList usage

Endpoints

GET /api/v1/orgs/{orgID}/build/device-policies

List device policies

Permission
workspaces:admin
Path parameters
orgID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

PUT /api/v1/orgs/{orgID}/build/device-policies/{class}

Replace one device policy

Permission
workspaces:admin
Path parameters
orgID, class
Request body
object
Response
200: DevicePolicy
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 415: content_type; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/devices

List devices

Permission
workspaces:create
Path parameters
orgID
Query parameters
class, host_id
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/lab-hosts

List lab hosts

Permission
workspaces:create
Path parameters
orgID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}

Get one lab host

Permission
workspaces:create
Path parameters
orgID, hostID
Response
200: LabHost
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

PATCH /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}

Update one lab host

Permission
workspaces:admin
Path parameters
orgID, hostID
Request body
LabHostPatch
Response
200: LabHost
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}/devices

List the devices of a lab host

Permission
workspaces:create
Path parameters
orgID, hostID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}/release-claims

Handles POST .../lab-hosts/{hostID}/release-claims (workspaces:admin, {"reason"}): releases the device claims a revoked host keeps until it confirms its teardown.

Permission
workspaces:admin
Path parameters
orgID, hostID
Request body
object
Response
200: LabHost
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/lab-hosts/{hostID}/revoke

Revoke a lab host

Permission
workspaces:admin
Path parameters
orgID, hostID
Request body
object
Response
200: LabHost
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/lab-hosts/enrolment-tokens

List enrolment tokens

Permission
workspaces:admin
Path parameters
orgID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/lab-hosts/enrolment-tokens

Create an enrolment token

Permission
workspaces:admin
Path parameters
orgID
Request body
TokenRequest
Response
201: CreatedToken
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 415: content_type; 503: policy_unavailable, unavailable

DELETE /api/v1/orgs/{orgID}/build/lab-hosts/enrolment-tokens/{tokenID}

Delete one enrolment token

Permission
workspaces:admin
Path parameters
orgID, tokenID
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/leases

List leases

Permission
workspaces:create
Path parameters
orgID
Query parameters
limit, scope, state
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}

Get one lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Response
200: Lease
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts

List the artifacts of a lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts

Create an artifact for a lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Query parameters
name, run_id
Response
201: Artifact
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts/{artifactID}

Get one artifact

Permission
workspaces:create
Path parameters
orgID, leaseID, artifactID
Response
200: Artifact
Errors
404: not_found

DELETE /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts/{artifactID}

Delete one artifact

Permission
workspaces:create
Path parameters
orgID, leaseID, artifactID
Errors
404: not_found

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/artifacts/{artifactID}/content

Content of an artifact

Permission
workspaces:create
Path parameters
orgID, leaseID, artifactID
Errors
404: not_found

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/caches

List the caches of a lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

PUT /api/v1/orgs/{orgID}/build/leases/{leaseID}/caches/{cacheName}/entries

Set the entries of a cach

Permission
workspaces:create
Path parameters
orgID, leaseID, cacheName
Query parameters
key
Response
201: value
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/caches/{cacheName}/restore

Restore of a cach

Permission
workspaces:create
Path parameters
orgID, leaseID, cacheName
Query parameters
key
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/kill

Kill a lease

Permission
workspaces:admin
Path parameters
orgID, leaseID
Request body
object
Response
200: Lease
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/release

Release a lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Response
200: Lease
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/renew

Renew a lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Request body
object
Response
200: Lease
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs

List the runs of a lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs

Create a run for a lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Request body
RunRequest
Response
201: Run
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}

Get one run

Permission
workspaces:create
Path parameters
orgID, leaseID, runID
Response
200: Run
Errors
404: not_found

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}/complete

Complete a run

Permission
workspaces:create
Path parameters
orgID, leaseID, runID
Request body
CompleteRequest
Response
200: Run
Errors
400: invalid_json; 404: not_found; 415: content_type

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}/log

Log of a run

Permission
workspaces:create
Path parameters
orgID, leaseID, runID
Errors
404: not_found

PUT /api/v1/orgs/{orgID}/build/leases/{leaseID}/runs/{runID}/log

Set the log of a run

Permission
workspaces:create
Path parameters
orgID, leaseID, runID
Errors
400: invalid_request; 404: not_found; 415: content_type

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/ssh

An SSH connection to a lab lease's host as binary WebSocket messages, for the holder in their own session while the lease is active and ready and the kill switch is off. The host must hold its relay connection to this replica (503 host_not_connected otherwise). The open and the end are audited (build.lease.ssh_relay); the caller's session, permission and the lease are checked again while the connection lasts.

Permission
workspaces:create
Path parameters
orgID, leaseID
Errors
400: invalid_request; 401: session_required, unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/ssh/certificate

Create a certificate

Permission
workspaces:create
Path parameters
orgID, leaseID
Request body
object
Response
200: CertificateResult
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/sync

Sync a lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Request body
SyncRequest
Response
200: SyncPlan
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/login-wipes

Answers the organization's owed login wipes to an administrator (audited).

Permission
workspaces:admin
Path parameters
orgID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/pools

List pools

Permission
workspaces:create
Path parameters
orgID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/pools

Create a pool

Permission
workspaces:admin
Path parameters
orgID
Request body
PoolSpec
Response
201: Pool
Errors
400: invalid_json, invalid_request, step_up_separately; 401: unauthorized; 403: forbidden, person_required; 415: content_type; 503: policy_unavailable, step_up_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/pools/{poolID}

Get one pool

Permission
workspaces:create
Path parameters
orgID, poolID
Response
200: Pool
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

PATCH /api/v1/orgs/{orgID}/build/pools/{poolID}

Update one pool

Permission
workspaces:admin
Path parameters
orgID, poolID
Response
200: Pool
Errors
400: invalid_json, invalid_request, step_up_separately; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, step_up_unavailable, unavailable

DELETE /api/v1/orgs/{orgID}/build/pools/{poolID}

Delete one pool

Permission
workspaces:admin
Path parameters
orgID, poolID
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/pools/{poolID}/caches

List the caches of a pool

Permission
workspaces:admin
Path parameters
orgID, poolID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

DELETE /api/v1/orgs/{orgID}/build/pools/{poolID}/caches/{cacheName}

Delete one cach

Permission
workspaces:admin
Path parameters
orgID, poolID, cacheName
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/pools/{poolID}/engines

List the engines of a pool

Permission
workspaces:admin
Path parameters
orgID, poolID
Response
200: PoolEngines
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: policy_unavailable, unavailable

POST /api/v1/orgs/{orgID}/build/pools/{poolID}/leases

Create a lease for a pool

Permission
workspaces:create
Path parameters
orgID, poolID
Request body
LeaseRequest
Response
201: Lease
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 415: content_type; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/quotas

List quotas

Permission
workspaces:admin
Path parameters
orgID
Response
200: Quotas
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

PUT /api/v1/orgs/{orgID}/build/quotas

Set quotas

Permission
workspaces:admin
Path parameters
orgID
Request body
object
Response
200: Quotas
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 415: content_type; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/task-engines

List task engines

Permission
workspaces:admin
Path parameters
orgID
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/usage

List usage

Permission
workspaces:create
Path parameters
orgID
Query parameters
scope
Response
200: Usage
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

Objects

object

FieldTypeDescription
reasonstring

object

FieldTypeDescription
reasonstring

object

FieldTypeDescription
reasonstring

object

FieldTypeDescription
ttl_secondsinteger

object

FieldTypeDescription
public_keystring

object

FieldTypeDescription
accessAccess
requires_approvalboolean
approver_group_id optionaluuid

object

FieldTypeDescription
max_active_leasesinteger
max_active_vcpusinteger
max_active_leases_per_personinteger
max_lease_hours_per_person_monthinteger

Access

Access says who may lease from a pool: the people, and (M3) the agents that may act for them.

FieldTypeDescription
all_membersboolean
user_idsarray of uuid
group_idsarray of uuid
agentsAgentAccessThe pool's agent policy; its zero value (and a pool stored before M3) admits no agent.

AgentAccess

AgentAccess says which agents may lease from a pool for the people its access policy admits.

FieldTypeDescription
modestringNone (default), listed or all.
agent_idsarray of uuid
secretsbooleanSecrets lets a lease taken by an agent receive the pool's secrets.

Artifact

A build artifact of a lease.

FieldTypeDescription
iduuid
lease_iduuid
run_id optionaluuid
namestring
size_bytesinteger
sha256string
created_byuuid
acting_agent_id optionaluuid
created_attimestamp
expires_attimestamp

CacheVolume

One cache of a pool: entries kept as objects, restored and saved by lease holders through the lease routes. It is not a volume mounted on the host: the server could not enforce one.

FieldTypeDescription
namestring
scopestring
max_bytesinteger
total_max_bytesintegerThe cache's total over every holder: in a holder-scope cache max_bytes is each holder's own budget; in a pool-scope cache it is max_bytes.
ttl_daysinteger
agentsstring

CertificateResult

A certificate for a lease's host.

FieldTypeDescription
certificatestring
serialstring
key_idstring
principalsarray of string
valid_aftertimestamp
valid_beforetimestamp
sshSSHTarget

CompleteRequest

CompleteRequest reports a run's outcome.

FieldTypeDescription
exit_code optionalinteger
duration_ms optionalinteger

CreatedToken

A new enrolment token; Token is shown once.

FieldTypeDescription
iduuid
tokenstring
namestring
expires_attimestamp

DevicePolicy

Who may claim a device class.

FieldTypeDescription
classstring
accessAccess
requires_approvalboolean
approver_group_id optionaluuidThe Directory group whose members may decide this class's lease approvals, besides holders of approvals:approve.
updated_by optionaluuid
updated_attimestamp

DeviceRequest

One device a lab lease claims: by device_id or by class, not both.

FieldTypeDescription
device_id optionaluuid
class optionalstring

Egress

The pool's egress policy.

FieldTypeDescription
modestring

Holder

Who holds a lease.

FieldTypeDescription
typestring
iduuid

Host

The state of a lease's host.

FieldTypeDescription
statusstring
ssh_user optionalstring
readyboolean

LabHost

A lab host.

FieldTypeDescription
iduuid
org_iduuid
namestring
statusstring
labelsobject of string
pool_idsarray of uuid
max_leasesinteger
disabledboolean
hostnamestring
osstring
archstring
os_versionstringThe OS release the host last reported (macOS product version, Linux kernel release); empty until an agent that reports it heartbeats.
versionstring
healthstring
ssh_host_keystringThe host's SSH host key as it last reported it (ssh-ed25519, authorized_keys form): clients pin it for SSH to a lab lease.
last_seen_at optionaltimestamp
certificate_not_aftertimestamp
active_leasesinteger
teardowns_owedinteger
devicesinteger
held_claimsintegerHeldClaims counts the host's devices claimed by a lease (held or awaiting release).
enrolled_attimestamp
revoked_at optionaltimestamp

LabHostPatch

LabHostPatch changes a lab host; nil fields keep their value.

FieldTypeDescription
name optionalstring
labels optionalobject of string
max_leases optionalinteger
disabled optionalboolean

LabSelector

LabSelector names the hosts of a lab pool: a host matches when it is listed, when it carries every label (an empty label set matches no host by labels), or when its enrolment token named the pool; and, whichever way it is named, only when it meets the pool's operating system and architecture requirement (OS and Arch; empty allows any).

FieldTypeDescription
host_idsarray of uuid
labelsobject of string
osarray of stringOS lists the operating systems the pool's hosts must run (linux, darwin); empty: any.
archarray of stringArch lists the architectures the pool's hosts must have (Go names: amd64, arm64, ...); empty: any.

Lease

One holder on one host of a pool.

FieldTypeDescription
iduuid
org_iduuid
pool_iduuid
holderHolder
acting_agent_id optionaluuid
statestring
sizeSize
purposestring
repostring
workspace_id optionaluuid
lab_host_id optionaluuid
approval_id optionalstring
devices optionalarray of LeaseDevice
host optionalHost
tasks_open optionalbooleanTasksOpen says whether the lease has an agent task that has not ended; set by the single lease read of a cloud or BYOC lease only.
created_attimestamp
expires_attimestamp
hard_expires_attimestamp
idle_timeout_secondsinteger
last_activity_attimestamp
renewalsinteger
ended_at optionaltimestamp
end_reason optionalstring

LeaseDevice

A device claimed by a lease.

FieldTypeDescription
device_iduuid
classstring
statestring

LeaseRequest

LeaseRequest asks for a lease of a pool.

FieldTypeDescription
ttl_secondsinteger
sizestring
purposestring
repostring
devices optionalarray of DeviceRequestClaimed on a lab pool's host: each entry names one device by ID or asks for any present, unclaimed device of a class.

Pool

An organization's set of build capacity.

FieldTypeDescription
iduuid
org_iduuid
namestring
descriptionstring
backendstring
template_id optionaluuid
template_version_id optionaluuid
lab optionalLabSelector
sizesarray of Size
default_sizestring
default_lease_ttl_secondsinteger
max_lease_ttl_secondsinteger
hard_max_secondsinteger
idle_timeout_secondsinteger
accessAccess
requires_approvalboolean
egressEgress
cache_volumesarray of CacheVolume
record_sessionsboolean
max_active_leasesinteger
log_retention_daysinteger
artifact_retention_daysintegerHow long artifacts of the pool's leases are kept (M3, 14.1).
disabledboolean
environment_id optionaluuid
secretsarray of SecretRefDelivered to every lease's host.
task_enginesarray of stringThe agent task engines the pool's hosts offer; empty offers none.
task_engine_modesobject of array of stringThe permissive modes (taskorder.Engine.Permissive) of each offered engine the pool allows, {engine: [mode]}; an engine absent offers only its non-permissive modes. Allowing one is re-verified (step-up build.task_permissive_mode:enable); never on lab pools.
task_model_accessobject of TaskEngineAccessPer engine the model access the pool offers; an engine absent from it offers gateway only. Loosening it is re-verified (step-up build.task_model_access:loosen).
created_by optionaluuid
created_attimestamp
updated_attimestamp
versioninteger

PoolEngine

One engine a pool offers, as its hosts report it.

FieldTypeDescription
enginestring
display_namestringHow Sandscale names the engine.
pinned_versionstringThe version the registry verified the engine at.
modesarray of stringThe engine's modes; PermissiveModes those of them that are permissive, and AllowedPermissiveModes those the pool allows.
permissive_modesarray of string
allowed_permissive_modesarray of string
hosts_reportingintegerThe pool's hosts with a fresh report; HostsInstalled those reporting the engine present, HostsVersionMatch those at the pinned version.
hosts_installedinteger
hosts_version_matchinteger
last_reported_at optionaltimestamp
statusstringStatus: installed (every reporting host has the pinned version), version_mismatch (every reporting host has it, not all at the pinned version), missing (a reporting host lacks it), unknown (no host reports).

PoolEngines

The engine report of a pool: its hosts are the hosts of its active leases.

FieldTypeDescription
pool_iduuid
hostsinteger
hosts_reportinginteger
hosts_with_sudointegerHostsWithSudo and HostsWithoutUserSwitch are reporting hosts where a permissive mode is refused (permissive_mode_with_sudo, permissive_mode_same_user).
hosts_without_user_switchinteger
enginesarray of PoolEngine

PoolSpec

The writable part of a pool. A PATCH decodes onto the current pool's spec.

FieldTypeDescription
namestring
descriptionstring
backendstring
template_id optionaluuid
template_version_id optionaluuid
lab optionalLabSelector
sizesarray of Size
default_sizestring
default_lease_ttl_secondsinteger
max_lease_ttl_secondsinteger
hard_max_secondsinteger
idle_timeout_secondsinteger
accessAccess
requires_approvalboolean
egressEgress
cache_volumesarray of CacheVolume
record_sessionsboolean
max_active_leasesinteger
log_retention_daysinteger
artifact_retention_daysinteger
disabledboolean
environment_id optionaluuid
secretsarray of SecretRef
task_enginesarray of string
task_model_accessobject of TaskEngineAccess
task_engine_modesobject of array of stringThe permissive engine modes the pool allows, {engine: [mode]}.
version optionalintegerVersion, when set on an update, must be the pool's current version.

Quotas

The organization's Build Hosts limits.

FieldTypeDescription
max_active_leasesinteger
max_active_vcpusinteger
max_active_leases_per_personinteger
max_lease_hours_per_person_monthinteger
updated_by optionaluuid
updated_at optionaltimestamp

Run

A command recorded on a lease before it runs.

FieldTypeDescription
iduuid
lease_iduuid
actor_iduuid
acting_agent_id optionaluuidThe agent that started the run for the holder (M3).
argvarray of string
cwdstring
commandstring
statestring
exit_code optionalinteger
reported_bystring
started_attimestamp
finished_at optionaltimestamp
duration_ms optionalinteger
logRunLogInfo

RunLogInfo

The size and digest of a run's stored log.

FieldTypeDescription
bytesinteger
sha256 optionalstring

RunRequest

RunRequest records a command to run on a lease's host.

FieldTypeDescription
argvarray of string
cwdstring

SSHTarget

FieldTypeDescription
userstring
workspace_id optionaluuid
lab_host_id optionaluuid
lease_id optionaluuid
host_key_aliasstring
host_key optionalstringA lab host's SSH host key (authorized_keys form) to pin, as the host last reported it; empty when it reported none yet.

SecretRef

One Vault value a pool delivers to its leases' hosts: a field of a vault path, as an environment variable (Env) or a file (File). A reference only, never a value.

FieldTypeDescription
pathstring
fieldstring
env optionalstring
file optionalstring

Size

One size a pool offers.

FieldTypeDescription
namestring
cpu_coresnumber
memory_gbnumber

SyncPlan

What the client runs: rsync over SSH with the lease's certificate.

FieldTypeDescription
directionstring
ssh_userstring
remote_dirstring
rsync_argsarray of string

SyncRequest

SyncRequest asks for a sync of a source tree with a lease's host.

FieldTypeDescription
directionstring
remote_dirstring

TaskEngineAccess

A pool's model access for one engine.

FieldTypeDescription
modesarray of stringThe model access modes the pool offers for the engine (gateway, vendor_account), each at most once, each one the engine supports.
organization_credentialstringOrganizationCredential names the organization's AI provider key in Vault (its provider the engine's vendor) that vendor_account tasks may use; "" none.
person_credentialsbooleanPersonCredentials lets each person's vendor_account tasks use the person's own API key.

TokenRequest

TokenRequest asks for a lab host enrolment token.

FieldTypeDescription
namestring
labelsobject of string
pool_idsarray of uuid
ttl_secondsinteger

Usage

Active and monthly usage, with the limits.

FieldTypeDescription
scopestring
monthstring
active_leasesinteger
active_vcpusnumber
lease_hours_monthnumber
active_leases_by_pool optionalobject of integer
limitsQuotas

This page is generated from the server's route table and the Go handlers that serve each route. Do not edit it by hand.