API by area

Agent Cloud and agent tasks

55 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}/agent-accountsList the agent accounts of an org
POST/api/v1/orgs/{orgID}/agent-accountsCreate an agent account for an org
GET/api/v1/orgs/{orgID}/agent-accounts/{accountID}Get one agent account
PATCH/api/v1/orgs/{orgID}/agent-accounts/{accountID}Update one agent account
DELETE/api/v1/orgs/{orgID}/agent-accounts/{accountID}Delete one agent account
PUT/api/v1/orgs/{orgID}/agent-accounts/{accountID}/allowed-usersSet the allowed users of an agent account
GET/api/v1/orgs/{orgID}/agent-accounts/{accountID}/bindingsList the bindings of an agent account
POST/api/v1/orgs/{orgID}/agent-accounts/{accountID}/bindingsCreate a binding for an agent account
DELETE/api/v1/orgs/{orgID}/agent-accounts/{accountID}/bindings/{bindingID}Delete one binding
PUT/api/v1/orgs/{orgID}/agent-accounts/{accountID}/ownerSet the owner of an agent account
GET/api/v1/orgs/{orgID}/agent-accounts/{accountID}/usageUsage of an agent account
GET/api/v1/orgs/{orgID}/agent-accounts/usageList usage
GET/api/v1/orgs/{orgID}/agent-accounts/workspacesList workspaces
GET/api/v1/orgs/{orgID}/build/engine-profilesList engine profiles
PUT/api/v1/orgs/{orgID}/build/engine-profiles/{engine}/egressSet the egress of an engine profile
GET/api/v1/orgs/{orgID}/build/governanceList governance
PUT/api/v1/orgs/{orgID}/build/governanceSets the organization's allowed modes and default; any change of either, in both directions, is re-verified (agent_governance:change).
GET/api/v1/orgs/{orgID}/build/leadsList leads
GET/api/v1/orgs/{orgID}/build/leads/{grantID}Get one lead
GET/api/v1/orgs/{orgID}/build/leads/{grantID}/tasksList the tasks of a lead
POST/api/v1/orgs/{orgID}/build/leads/{grantID}/tasksCreate a task for a lead
GET/api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}Get one task
GET/api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/logLog of a task
POST/api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/moveMove a task
GET/api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/reportReport of a task
POST/api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/retryRetry a task
POST/api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/stopStop a task
GET/api/v1/orgs/{orgID}/build/leads/{grantID}/usageUsage of a lead
GET/api/v1/orgs/{orgID}/build/leads/{grantID}/workersList the workers of a lead
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/engine-signinsCreate an engine signin for a lease
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/engine-signins/{signinID}Get one engine signin
DELETE/api/v1/orgs/{orgID}/build/leases/{leaseID}/engine-signins/{signinID}Delete one engine signin
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasksList the tasks of a lease
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasksCreate a task for a lease
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}Get one task
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/branchBranch a task
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/cancelCancel a task
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/changesList the changes of a task
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/diffDiff of a task
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/fileFile of a task
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/filesList the files of a task
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/handbackHandback a task
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/keep-leaseKeeps the lease Sandscale took for a task after the task ends (the task's person).
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/liveServes the live view as server-sent events: "log" and "file" events with their cursor as id (resume with Last-Event-ID, or ?after=), a "state" event when the task's state or take-over changes, and a final "closed" event with the reason the view ended. The stream ends after buildhosts.LiveStreamMax; the client reconnects with its last id.
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/live/diffList diff
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/live/eventsList events
GET/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/logLog of a task
POST/api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/takeoverTakeover a task
GET/api/v1/orgs/{orgID}/build/task-costsAnswers the cost totals of tasks created in [since, until) (default the last 30 days): ?scope=mine (default) by pool, organization (workspaces:admin) by pool and person.
GET/api/v1/orgs/{orgID}/build/task-credentialsList task credentials
PUT/api/v1/orgs/{orgID}/build/task-credentials/{vendor}Stores the caller's own credential of a vendor: their own session, through their Device agent (X-Device-Token and a device proof of this exact request, purpose build.task.credential), re-verified (task_vendor_credential:store, decided by the authentication middleware's step-up gate). The answer never holds the credential.
DELETE/api/v1/orgs/{orgID}/build/task-credentials/{vendor}Delete one task credential
GET/api/v1/orgs/{orgID}/build/tasksLists tasks across leases: ?scope=mine (default, the caller's own) or organization (workspaces:admin, metadata only), filters state, engine, pool_id, since, and cursor and limit for pages.
POST/api/v1/orgs/{orgID}/build/tasksStarts a task on a pool: the body of a start on a lease plus pool_id and the lease's size and keep_lease, with the same device token and device proof of this exact request (purpose build.task.start, audience build-task). 201 with the task, queued or pending.
GET/api/v1/orgs/{orgID}/build/workersLists the cloud agent workspaces of the Agent Cloud board: ?scope=mine (default, the caller's own; lead_grant_id decides each worker's covered flag against one of their lead grants) or organization (workspaces:admin, metadata only, audited). The person's own session only: agents list workers through their lead grant.

Endpoints

GET /api/v1/orgs/{orgID}/agent-accounts

List the agent accounts of an org

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

POST /api/v1/orgs/{orgID}/agent-accounts

Create an agent account for an org

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

GET /api/v1/orgs/{orgID}/agent-accounts/{accountID}

Get one agent account

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

PATCH /api/v1/orgs/{orgID}/agent-accounts/{accountID}

Update one agent account

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

DELETE /api/v1/orgs/{orgID}/agent-accounts/{accountID}

Delete one agent account

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

PUT /api/v1/orgs/{orgID}/agent-accounts/{accountID}/allowed-users

Set the allowed users of an agent account

Permission
workspaces:create
Path parameters
orgID, accountID
Request body
AllowedUsers
Response
200: Account
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}/agent-accounts/{accountID}/bindings

List the bindings of an agent account

Permission
workspaces:create
Path parameters
orgID, accountID
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}/agent-accounts/{accountID}/bindings

Create a binding for an agent account

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

DELETE /api/v1/orgs/{orgID}/agent-accounts/{accountID}/bindings/{bindingID}

Delete one binding

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

PUT /api/v1/orgs/{orgID}/agent-accounts/{accountID}/owner

Set the owner of an agent account

Permission
workspaces:create
Path parameters
orgID, accountID
Request body
object
Response
200: Account
Errors
400: invalid_account, 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}/agent-accounts/{accountID}/usage

Usage of an agent account

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

GET /api/v1/orgs/{orgID}/agent-accounts/usage

List usage

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

GET /api/v1/orgs/{orgID}/agent-accounts/workspaces

List workspaces

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/engine-profiles

List engine profiles

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

PUT /api/v1/orgs/{orgID}/build/engine-profiles/{engine}/egress

Set the egress of an engine profile

Permission
workspaces:admin
Path parameters
orgID, engine
Request body
object
Response
200: EngineProfile
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 413: request_too_large; 503: policy_unavailable, unavailable

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

List governance

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

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

Sets the organization's allowed modes and default; any change of either, in both directions, is re-verified (agent_governance:change).

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

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

List leads

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

GET /api/v1/orgs/{orgID}/build/leads/{grantID}

Get one lead

Permission
workspaces:create
Path parameters
orgID, grantID
Response
200: LeadGrant
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: unavailable

GET /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks

List the tasks of a lead

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

POST /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks

Create a task for a lead

Permission
workspaces:create
Path parameters
orgID, grantID
Request body
LeadDispatchBody
Response
201: LeadTask
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 413: request_too_large; 415: content_type; 503: unavailable

GET /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}

Get one task

Permission
workspaces:create
Path parameters
orgID, grantID, leadTaskID
Response
200: LeadTask
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: lead_task_not_found; 503: unavailable

GET /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/log

Log of a task

Permission
workspaces:create
Path parameters
orgID, grantID, leadTaskID
Query parameters
limit, offset
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: lead_task_not_found; 503: unavailable

POST /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/move

Move a task

Permission
workspaces:create
Path parameters
orgID, grantID, leadTaskID
Request body
LeadMoveBody
Response
201: LeadTask
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: lead_task_not_found; 413: request_too_large; 415: content_type; 503: unavailable

GET /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/report

Report of a task

Permission
workspaces:create
Path parameters
orgID, grantID, leadTaskID
Response
200: TaskResult
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: lead_task_not_found; 503: unavailable

POST /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/retry

Retry a task

Permission
workspaces:create
Path parameters
orgID, grantID, leadTaskID
Response
201: LeadTask
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: lead_task_not_found; 503: unavailable

POST /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/stop

Stop a task

Permission
workspaces:create
Path parameters
orgID, grantID, leadTaskID
Response
200: LeadTask
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: lead_task_not_found; 503: unavailable

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

Usage of a lead

Permission
workspaces:create
Path parameters
orgID, grantID
Response
200: LeadUsage
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: unavailable

GET /api/v1/orgs/{orgID}/build/leads/{grantID}/workers

List the workers of a lead

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

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/engine-signins

Create an engine signin for a lease

Permission
workspaces:create
Path parameters
orgID, leaseID
Request body
object
Response
201: EngineSignin
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, person_required; 404: not_found; 413: request_too_large; 503: policy_unavailable, unavailable

GET /api/v1/orgs/{orgID}/build/leases/{leaseID}/engine-signins/{signinID}

Get one engine signin

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

DELETE /api/v1/orgs/{orgID}/build/leases/{leaseID}/engine-signins/{signinID}

Delete one engine signin

Permission
workspaces:create
Path parameters
orgID, leaseID, signinID
Response
200: EngineSignin
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}/tasks

List the tasks 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}/tasks

Create a task for a lease

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

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

Get one task

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Response
200: value
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}/tasks/{taskID}/branch

Branch a task

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Response
TaskBranch
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}/tasks/{taskID}/cancel

Cancel a task

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Response
200: 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}/tasks/{taskID}/changes

List the changes of a task

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Response
200: TaskResult
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}/tasks/{taskID}/diff

Diff of a task

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
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}/tasks/{taskID}/file

File of a task

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Query parameters
path
Response
200: TaskFileView
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}/tasks/{taskID}/files

List the files of a task

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Query parameters
path
Response
200: TaskTree
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}/tasks/{taskID}/handback

Handback a task

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

POST /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/keep-lease

Keeps the lease Sandscale took for a task after the task ends (the task's person).

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Response
200: 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}/tasks/{taskID}/live

Serves the live view as server-sent events: "log" and "file" events with their cursor as id (resume with Last-Event-ID, or ?after=), a "state" event when the task's state or take-over changes, and a final "closed" event with the reason the view ended. The stream ends after buildhosts.LiveStreamMax; the client reconnects with its last id.

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Query parameters
after
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}/tasks/{taskID}/live/diff

List diff

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
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}/tasks/{taskID}/live/events

List events

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Query parameters
after, limit
Response
200: LivePage
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}/tasks/{taskID}/log

Log of a task

Permission
workspaces:create
Path parameters
orgID, leaseID, taskID
Query parameters
limit, offset
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}/tasks/{taskID}/takeover

Takeover a task

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

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

Answers the cost totals of tasks created in [since, until) (default the last 30 days): ?scope=mine (default) by pool, organization (workspaces:admin) by pool and person.

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

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

List task credentials

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

PUT /api/v1/orgs/{orgID}/build/task-credentials/{vendor}

Stores the caller's own credential of a vendor: their own session, through their Device agent (X-Device-Token and a device proof of this exact request, purpose build.task.credential), re-verified (task_vendor_credential:store, decided by the authentication middleware's step-up gate). The answer never holds the credential.

Permission
workspaces:create
Path parameters
orgID, vendor
Request body
buildTaskCredentialBody
Response
200: TaskCredential
Errors
400: invalid_json, invalid_request; 401: device_proof_invalid, unauthorized; 403: forbidden, person_required; 413: request_too_large; 415: content_type; 503: policy_unavailable, unavailable

DELETE /api/v1/orgs/{orgID}/build/task-credentials/{vendor}

Delete one task credential

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

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

Lists tasks across leases: ?scope=mine (default, the caller's own) or organization (workspaces:admin, metadata only), filters state, engine, pool_id, since, and cursor and limit for pages.

Permission
workspaces:create
Path parameters
orgID
Query parameters
cursor, engine, limit, pool_id, scope, since, state
Response
200: TaskPage
Errors
400: invalid_request; 401: unauthorized; 403: forbidden, person_required; 503: policy_unavailable, unavailable

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

Starts a task on a pool: the body of a start on a lease plus pool_id and the lease's size and keep_lease, with the same device token and device proof of this exact request (purpose build.task.start, audience build-task). 201 with the task, queued or pending.

Permission
workspaces:create
Path parameters
orgID
Request body
buildPoolTaskStartBody
Response
201: value
Errors
400: invalid_json, invalid_request; 401: device_proof_invalid, unauthorized; 403: forbidden, person_required; 413: request_too_large; 415: content_type; 503: policy_unavailable, unavailable

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

Lists the cloud agent workspaces of the Agent Cloud board: ?scope=mine (default, the caller's own; lead_grant_id decides each worker's covered flag against one of their lead grants) or organization (workspaces:admin, metadata only, audited). The person's own session only: agents list workers through their lead grant.

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

Objects

object

FieldTypeDescription
workspace_idstring

object

FieldTypeDescription
enginestring

object

No fields.

object

FieldTypeDescription
modestring

object

FieldTypeDescription
owner_idstring

object

FieldTypeDescription
hosts optionalarray of string

object

FieldTypeDescription
allowed_modesarray of string
default_modestring

Account

An agent account as the routes show it: never a credential.

FieldTypeDescription
iduuid
labelstring
typestring
vendorstring
engine optionalstringThe engine whose client signs in (every login type); null for an API key usable by every engine of its vendor that takes a vendor key.
enginesarray of stringThe engines that can run under the account.
owner_iduuid
credential_source optionalstringCredentialSource and CredentialRef name where an api_key account's key is: organization (an AI provider key of the organization's Vault, by name) or person (the owner's own sealed key, by ID). Null for the login types.
credential_ref optionalstring
allowed_user_idsarray of uuid
allowed_group_idsarray of uuid
statestring
state_reason optionalstring
created_by optionaluuid
created_attimestamp
updated_attimestamp
binding optionalAccountBindingThe account's active workspace binding, if any, shown only to the account's owner, an administrator and the binding's own person (whose workspace it is). InUse says whether the account has an active binding, for everyone who sees the account.
in_useboolean
can_managebooleanCanManage and CanUse are the caller's rights, decided by the server.
can_useboolean
terms_note optionalstringShown with a personal login: the vendor's own terms apply to the person's account.

AccountBinding

An account's binding to a workspace as the routes show it.

FieldTypeDescription
iduuid
account_iduuid
workspace_iduuid
lease_id optionaluuid
person_iduuid
statestring
bound_byuuid
bound_attimestamp
ended_at optionaltimestamp
end_reason optionalstring
signin_statestring
signin_evidence optionalstring
signin_reported_at optionaltimestamp
wipe_statestring
wipe_reason optionalstring
wiped_at optionaltimestamp
at_rest_encryptionstringWhat protects a login on the workspace's home storage, as provisioning recorded it: provider_volume_encrypted (the workspace's home volume is on a disk its host verified encrypted at rest) or unknown (logins are refused there: login_storage_unencrypted).

AccountPatch

AccountPatch changes an account's label or state (active, disabled).

FieldTypeDescription
label optionalstring
state optionalstring

AccountSpec

An account to create.

FieldTypeDescription
labelstring
typestring
enginestring
vendorstring
owner_idstringThe owning person (empty: the caller).
credential_refstringCredentialRef names the organization's AI provider key for an api_key account.
allowed_user_idsarray of uuid
allowed_group_idsarray of uuid

AllowedUsers

An account's allowed people and Directory groups.

FieldTypeDescription
user_idsarray of uuid
group_idsarray of uuid

BoardWorkers

The Agent Cloud board's list of workers.

FieldTypeDescription
scopestring
workersarray of Worker
lead_grant_idstringThe lead grant the workers' covered flags were decided against ("" none).

EgressEnforcement

What Sandscale knows of an engine's allowlist on the organization's active lease hosts whose pools offer it.

FieldTypeDescription
statestringState: enforced (every host's proxy has the current list, or admits nothing but Sandscale), partial, pending (not reported yet), not_enforced (no host has a proxy to enforce it), no_hosts.
hostsinteger
appliedintegerApplied hosts admit the list and nothing else; Closed hosts (network access None) admit only Sandscale; NoProxy hosts enforce nothing (Full access or no environment); Pending hosts have not reported the current revision.
closedinteger
no_proxyinteger
pendinginteger

EngineProfile

An engine profile as the routes show it, with the organization's allowlist.

FieldTypeDescription
enginestring
display_namestring
availableboolean
unavailable_reasonstring
packagestring
versionstring
install_methodstring
signin_methodsarray of string
login_commandstring
credential_pathsarray of string
default_egress_hostsarray of string
gateway_base_url_variablestring
evidencestring
governancestringManaged_hooks (the engine's own managed policy carries hooks to Sandscale) or edges_only (egress, audit, telemetry, the verified check), with the reason.
governance_reasonstring
managed_policy_pathstring
modesarray of stringModes and Access are the registry's for an engine Sandscale runs.
accessarray of string
egress_hostsarray of stringThe organization's allowlist (the profile's defaults until an administrator sets one); EgressCustomized reports a set one.
egress_customizedboolean
egress_updated_at optionaltimestamp
egress_updated_by optionaluuid
egress_enforcement optionalEgressEnforcementWhat the organization's lease hosts report of the allowlist; set on the organization's reads.

EngineSignin

An engine sign-in as its person sees it. VerificationURL and UserCode are set only while it is prompted.

FieldTypeDescription
iduuid
lease_iduuid
workspace_iduuid
enginestring
methodstring
statestring
verification_url optionalstring
user_code optionalstring
created_attimestamp
prompted_at optionaltimestamp
expires_attimestamp
ended_at optionaltimestamp
end_reason optionalstring
terms_notestringThe one-line guardrail shown with every sign-in: the vendor's own terms apply to the account the person signs in with.
login_storagestringThe basis on which the login is kept in the workspace: its home storage recorded as encrypted at rest (provider_volume_encrypted) when the sign-in started.

GovernanceSettings

The organization's governance floor: the modes a task may run in and the mode of a task that names none.

FieldTypeDescription
allowed_modesarray of string
default_modestring
updated_at optionaltimestamp
updated_by optionaluuid

HandbackAnswer

HandbackAnswer answers a hand-back.

FieldTypeDescription
takeoverTaskTakeover
taskvalue
follow_up optionalTaskFollowUp

LeadAccountUsage

The lead's use of one account.

FieldTypeDescription
account_id optionaluuid
label optionalstring
type optionalstring
vendor optionalstring
tasksinteger
tasks_runninginteger
runtime_secondsinteger
gateway_spent_microsinteger
model_requestsinteger
input_tokensinteger
output_tokensinteger

LeadGrant

A lead grant as the lead routes show it.

FieldTypeDescription
idstring
organization_idstring
person_idstring
device_idstring
enginestring
project_idstring
descriptionstring
max_runtime_secondsinteger
budget_microsinteger
spent_microsinteger
reserved_microsinteger
statestring
end_reason optionalstring
ended_by optionalstring
created_attimestamp
expires_attimestamp
started_at optionaltimestamp
ended_at optionaltimestamp
kindstring"task" (one task) or "lead".
lead_id optionalstring
lead_scope optionalLeadScope
budgetLeadBudget
swarm_idstringThe swarm that shows the lead in the console's swarm views (the same id).

LeadTask

A task of a lead.

FieldTypeDescription
iduuid
lead_grant_iduuid
person_iduuid
statestring
targetstring
target_lease_id optionaluuid
target_account_id optionaluuid
target_pool_id optionaluuid
enginestring
modestring
accessstring
credential_source optionalstring
governance_modestringThe mode the lead chose (observe, enforce; "" the organization's default).
repositorystring
refstring
connection_id optionaluuid
cwdstring
brief_sha256string
brief_bytesinteger
max_runtime_secondsinteger
budget_microsinteger
previous_id optionaluuid
relation optionalstring
lead_viastring
lead_agent_id optionaluuid
lead_clientstring
lease_id optionaluuid
task_id optionaluuid
task_delegation_id optionaluuid
attemptsinteger
last_refusal optionalstring
end_reason optionalstring
created_attimestamp
dispatched_at optionaltimestamp
ended_at optionaltimestamp
queue_position optionalintegerThe task's place in its lead's queue (1 first), for a queued task.
task optionalvalueThe build task it became (its state, outcome, account, cost), once dispatched.
engine_namestringHow Sandscale names Engine.

LeadUsage

A lead grant's usage: its budget and the use of each account by its tasks.

FieldTypeDescription
grantLeadGrant
accountsarray of LeadAccountUsage
queuedinteger

LiveEvent

One event of the live view: a log chunk (Data, the bytes as the agent sent them, base64) or a file event.

FieldTypeDescription
idstringThe cursor after this event (the SSE event id).
typestring
seqinteger
data optionalstringLog.
path optionalstringFile.
kind optionalstring
size optionalinteger
at optionaltimestamp

LivePage

One page of the live view.

FieldTypeDescription
eventsarray of LiveEvent
cursorstringWhere the next page starts (also the last event's ID).
morebooleanSet when more events are waiting.
statestring
closed optionalstringSet when the live view ends: the task ended (task_ended) or no longer holds. A client stops then.
takeover optionalTaskTakeover

TakeoverAnswer

TakeoverAnswer answers a take-over.

FieldTypeDescription
takeoverTaskTakeover
taskvalue
terminalTakeoverTerminal

TakeoverTerminal

TakeoverTerminal names how the person reaches the task's directory: the host's existing web terminal and the lease's SSH certificate (no other terminal is opened).

FieldTypeDescription
workspace_iduuid
directorystring
web_terminalstring
ssh_certificatestring

TaskBranch

The branch and pull request opened from a task's result.

FieldTypeDescription
connection_iduuid
repositorystring
branchstring
commitstring
pull_requestinteger
urlstring
created_attimestamp
created_byuuid
replayedbooleanTrue when the branch was opened by an earlier request.

TaskChangedFileEntry

One file of a change set in a summary (never its content).

FieldTypeDescription
pathstring
statusstring
executableboolean
bytesinteger
sha256 optionalstring
binaryboolean

TaskCostGroup

The total of a group of tasks.

FieldTypeDescription
idstring
tasksinteger
host_secondsinteger
host_microsinteger
model_microsinteger
total_microsinteger
totalMoney
estimated_tasksinteger

TaskCostTotals

The costs of the tasks created in a window, in total, per pool and (for administrators) per person.

FieldTypeDescription
scopestring
sincetimestamp
untiltimestamp
totalTaskCostGroup
by_poolarray of TaskCostGroup
by_person optionalarray of TaskCostGroup
truncatedboolean
notestring

TaskCredential

A person's stored vendor credential as the routes show it: never its value, not even a part of it.

FieldTypeDescription
iduuid
vendorstring
credential_typestring
enginesarray of stringThe engines of the registry that use this vendor.
created_attimestamp
updated_attimestamp
last_used_at optionaltimestamp

TaskFileView

One file of a running task's directory.

FieldTypeDescription
pathstring
sizeinteger
binaryboolean
executableboolean
content optionalstringThe file's text; absent for a binary file.

TaskFollowUp

What the person starts after handing back a stopped task: a new task on the same lease and working directory, through the normal start (their Device agent, a new delegation).

FieldTypeDescription
lease_iduuid
modestring
cwdstring
enginestring
startstringStart names the only way to start it.

TaskPage

One page of a task list, newest first.

FieldTypeDescription
tasksarray of value
next_cursor optionalstring
scopestring
settingsTaskSettings

TaskResult

A task's result as the routes show it.

FieldTypeDescription
task_iduuid
statestring
refusal_reason optionalstring
refusal_detail optionalstring
refused_by optionalstring
base_sha256string
change_sha256 optionalstring
filesinteger
addedinteger
modifiedinteger
deletedinteger
content_bytesinteger
excludedarray of Excluded
created_attimestamp
expires_attimestamp
result_deletedboolean
branch optionalTaskBranch
changes optionalarray of TaskChangedFileEntry

TaskSettings

The deployment's settings a client shows next to tasks, read only.

FieldTypeDescription
branch_prefixstringSCM write mode's branch prefix (NI_AUTH_SCM_WRITE_BRANCH_PREFIX); a task's branch is TaskBranchPattern with the task's ID.
task_branch_patternstring
queue_max_secondsinteger
auto_lease_linger_secondsinteger

TaskTakeover

A take-over of a task.

FieldTypeDescription
iduuid
task_iduuid
person_iduuid
modestring
statestringOpen, handed_back or closed (the task ended while taken over).
directorystring
taken_attimestamp
ended_at optionaltimestamp
handback optionalstring
close_reason optionalstring

TaskTree

One directory of a running task's directory.

FieldTypeDescription
pathstring
entriesarray of TaskTreeEntry
hiddenintegerHidden counts the entries left out (the deny-list, the engine's state, invalid names).
truncatedboolean

TaskTreeEntry

One entry of a directory of the task's directory.

FieldTypeDescription
namestring
typestring
sizeinteger
executable optionalboolean

Worker

One of the person's cloud agent workspaces: an active lease with a host.

FieldTypeDescription
lease_iduuid
holder_iduuid
workspace_iduuid
pool_iduuid
pool_namestring
enginesarray of string
account optionalWorkerAccount
statestring
current_task optionalWorkerTask
coveredboolean
expires_attimestamp
hard_expires_attimestamp
engine_namesarray of stringHow Sandscale names Engines, in the same order.

WorkerAccount

The agent account bound to a worker.

FieldTypeDescription
iduuid
labelstring
typestring
vendorstring
engine optionalstring
binding_iduuid
signin_statestring

WorkerTask

The task a worker runs now.

FieldTypeDescription
iduuid
statestring
enginestring
started_at optionaltimestamp
lead_task_id optionaluuid

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

LeadBudget

A lead grant's budget: committed is what the delegations minted from it hold (the whole budget of an active one, what an ended one spent or still reserves).

FieldTypeDescription
budget_microsinteger
committed_microsinteger
spent_microsinteger
active_task_delegationsinteger

LeadScope

What a lead grant covers. The person's device proved exactly this.

FieldTypeDescription
enginesarray of stringEngines the lead's tasks may run (at least one, of the build task registry).
workspace_ids optionalarray of stringWorkspaceIDs, AccountIDs and PoolIDs name the person's workers the lead may use: a worker (an active lease of the person with a host) is covered when its workspace, the agent account bound to it, or its lease's pool is named. At least one is named.
account_ids optionalarray of string
pool_ids optionalarray of string
repositoriesarray of stringRepositories the lead's tasks may take as their source ("owner/name"; at least one).
modesarray of stringModes (edit, full) and Access (gateway, vendor_account, own_login) a task may use: the governance mode. own_login covers the tasks of workers bound to a seat, a company login or a personal login, signed in inside the workspace.
accessarray of string
task_budget_microsintegerThe most model budget one task may take of the grant's budget.
max_parallelintegerHow many of the lead's tasks may run at once (1 to 20, default 3).

Excluded

Excluded counts the files the agent left out of a change set for one reason: "engine_state", or "denied:<rule>" and "denied_content:<rule>" of the platform's compiled-in deny-list. Their paths are not sent.

FieldTypeDescription
reasonstring
filesinteger

LeadDispatchBody

FieldTypeDescription
targetstring
lease_idstring
account_idstring
pool_idstring
enginestring
modestring
accessstring
credential_sourcestring
repositorystring
refstring
connection_idstring
cwdstring
briefstring
max_runtime_secondsinteger
budget_microsinteger
governance_modestring

LeadMoveBody

FieldTypeDescription
targetstring
lease_idstring
account_idstring
pool_idstring

buildPoolTaskStartBody

FieldTypeDescription
task_delegation_idstring
modestring
taskstring
cwdstring
max_runtime_secondsinteger
accessstringThe model access (gateway, the default, or vendor_account) and CredentialSource where a vendor_account task's credential comes from (organization or person).
credential_sourcestring
source optionalv1.buildTaskSourceBodyThe repository and ref delivered to the task's directory.
governance_modestringObserve or enforce ("" the organization's default; engine profiles).
pool_idstring
sizestring
keep_leaseboolean

buildTaskCredentialBody

FieldTypeDescription
credential_typestring
secretstring

buildTaskSourceBody

FieldTypeDescription
repositorystring
refstring
connection_idstring

buildTaskStartBody

FieldTypeDescription
task_delegation_idstring
modestring
taskstring
cwdstring
max_runtime_secondsinteger
accessstringThe model access (gateway, the default, or vendor_account) and CredentialSource where a vendor_account task's credential comes from (organization or person).
credential_sourcestring
source optionalv1.buildTaskSourceBodyThe repository and ref delivered to the task's directory.
governance_modestringObserve or enforce ("" the organization's default; engine profiles).

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