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
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/orgs/{orgID}/agent-accounts | List the agent accounts of an org |
POST | /api/v1/orgs/{orgID}/agent-accounts | Create 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-users | Set the allowed users of an agent account |
GET | /api/v1/orgs/{orgID}/agent-accounts/{accountID}/bindings | List the bindings of an agent account |
POST | /api/v1/orgs/{orgID}/agent-accounts/{accountID}/bindings | Create 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}/owner | Set the owner of an agent account |
GET | /api/v1/orgs/{orgID}/agent-accounts/{accountID}/usage | Usage of an agent account |
GET | /api/v1/orgs/{orgID}/agent-accounts/usage | List usage |
GET | /api/v1/orgs/{orgID}/agent-accounts/workspaces | List workspaces |
GET | /api/v1/orgs/{orgID}/build/engine-profiles | List engine profiles |
PUT | /api/v1/orgs/{orgID}/build/engine-profiles/{engine}/egress | Set the egress of an engine profile |
GET | /api/v1/orgs/{orgID}/build/governance | List governance |
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). |
GET | /api/v1/orgs/{orgID}/build/leads | List leads |
GET | /api/v1/orgs/{orgID}/build/leads/{grantID} | Get one lead |
GET | /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks | List the tasks of a lead |
POST | /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks | Create 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}/log | Log of a task |
POST | /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/move | Move a task |
GET | /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/report | Report of a task |
POST | /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/retry | Retry a task |
POST | /api/v1/orgs/{orgID}/build/leads/{grantID}/tasks/{leadTaskID}/stop | Stop a task |
GET | /api/v1/orgs/{orgID}/build/leads/{grantID}/usage | Usage of a lead |
GET | /api/v1/orgs/{orgID}/build/leads/{grantID}/workers | List the workers of a lead |
POST | /api/v1/orgs/{orgID}/build/leases/{leaseID}/engine-signins | Create 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}/tasks | List the tasks of a lease |
POST | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks | Create 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}/branch | Branch a task |
POST | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/cancel | Cancel a task |
GET | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/changes | List the changes of a task |
GET | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/diff | Diff of a task |
GET | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/file | File of a task |
GET | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/files | List the files of a task |
POST | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/handback | Handback a task |
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). |
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. |
GET | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/live/diff | List diff |
GET | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/live/events | List events |
GET | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/log | Log of a task |
POST | /api/v1/orgs/{orgID}/build/leases/{leaseID}/tasks/{taskID}/takeover | Takeover a task |
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. |
GET | /api/v1/orgs/{orgID}/build/task-credentials | List 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/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. |
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. |
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. |
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
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
| Field | Type | Description |
|---|---|---|
workspace_id | string |
object
| Field | Type | Description |
|---|---|---|
engine | string |
object
No fields.
object
| Field | Type | Description |
|---|---|---|
mode | string |
object
| Field | Type | Description |
|---|---|---|
owner_id | string |
object
| Field | Type | Description |
|---|---|---|
hosts optional | array of string |
object
| Field | Type | Description |
|---|---|---|
allowed_modes | array of string | |
default_mode | string |
Account
An agent account as the routes show it: never a credential.
| Field | Type | Description |
|---|---|---|
id | uuid | |
label | string | |
type | string | |
vendor | string | |
engine optional | string | The 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. |
engines | array of string | The engines that can run under the account. |
owner_id | uuid | |
credential_source optional | string | CredentialSource 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 optional | string | |
allowed_user_ids | array of uuid | |
allowed_group_ids | array of uuid | |
state | string | |
state_reason optional | string | |
created_by optional | uuid | |
created_at | timestamp | |
updated_at | timestamp | |
binding optional | AccountBinding | The 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_use | boolean | |
can_manage | boolean | CanManage and CanUse are the caller's rights, decided by the server. |
can_use | boolean | |
terms_note optional | string | Shown 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.
| Field | Type | Description |
|---|---|---|
id | uuid | |
account_id | uuid | |
workspace_id | uuid | |
lease_id optional | uuid | |
person_id | uuid | |
state | string | |
bound_by | uuid | |
bound_at | timestamp | |
ended_at optional | timestamp | |
end_reason optional | string | |
signin_state | string | |
signin_evidence optional | string | |
signin_reported_at optional | timestamp | |
wipe_state | string | |
wipe_reason optional | string | |
wiped_at optional | timestamp | |
at_rest_encryption | string | What 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).
| Field | Type | Description |
|---|---|---|
label optional | string | |
state optional | string |
AccountSpec
An account to create.
| Field | Type | Description |
|---|---|---|
label | string | |
type | string | |
engine | string | |
vendor | string | |
owner_id | string | The owning person (empty: the caller). |
credential_ref | string | CredentialRef names the organization's AI provider key for an api_key account. |
allowed_user_ids | array of uuid | |
allowed_group_ids | array of uuid |
AllowedUsers
An account's allowed people and Directory groups.
| Field | Type | Description |
|---|---|---|
user_ids | array of uuid | |
group_ids | array of uuid |
BoardWorkers
The Agent Cloud board's list of workers.
| Field | Type | Description |
|---|---|---|
scope | string | |
workers | array of Worker | |
lead_grant_id | string | The 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.
| Field | Type | Description |
|---|---|---|
state | string | State: 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. |
hosts | integer | |
applied | integer | Applied 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. |
closed | integer | |
no_proxy | integer | |
pending | integer |
EngineProfile
An engine profile as the routes show it, with the organization's allowlist.
| Field | Type | Description |
|---|---|---|
engine | string | |
display_name | string | |
available | boolean | |
unavailable_reason | string | |
package | string | |
version | string | |
install_method | string | |
signin_methods | array of string | |
login_command | string | |
credential_paths | array of string | |
default_egress_hosts | array of string | |
gateway_base_url_variable | string | |
evidence | string | |
governance | string | Managed_hooks (the engine's own managed policy carries hooks to Sandscale) or edges_only (egress, audit, telemetry, the verified check), with the reason. |
governance_reason | string | |
managed_policy_path | string | |
modes | array of string | Modes and Access are the registry's for an engine Sandscale runs. |
access | array of string | |
egress_hosts | array of string | The organization's allowlist (the profile's defaults until an administrator sets one); EgressCustomized reports a set one. |
egress_customized | boolean | |
egress_updated_at optional | timestamp | |
egress_updated_by optional | uuid | |
egress_enforcement optional | EgressEnforcement | What 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.
| Field | Type | Description |
|---|---|---|
id | uuid | |
lease_id | uuid | |
workspace_id | uuid | |
engine | string | |
method | string | |
state | string | |
verification_url optional | string | |
user_code optional | string | |
created_at | timestamp | |
prompted_at optional | timestamp | |
expires_at | timestamp | |
ended_at optional | timestamp | |
end_reason optional | string | |
terms_note | string | The one-line guardrail shown with every sign-in: the vendor's own terms apply to the account the person signs in with. |
login_storage | string | The 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.
| Field | Type | Description |
|---|---|---|
allowed_modes | array of string | |
default_mode | string | |
updated_at optional | timestamp | |
updated_by optional | uuid |
HandbackAnswer
HandbackAnswer answers a hand-back.
| Field | Type | Description |
|---|---|---|
takeover | TaskTakeover | |
task | value | |
follow_up optional | TaskFollowUp |
LeadAccountUsage
The lead's use of one account.
| Field | Type | Description |
|---|---|---|
account_id optional | uuid | |
label optional | string | |
type optional | string | |
vendor optional | string | |
tasks | integer | |
tasks_running | integer | |
runtime_seconds | integer | |
gateway_spent_micros | integer | |
model_requests | integer | |
input_tokens | integer | |
output_tokens | integer |
LeadGrant
A lead grant as the lead routes show it.
| Field | Type | Description |
|---|---|---|
id | string | |
organization_id | string | |
person_id | string | |
device_id | string | |
engine | string | |
project_id | string | |
description | string | |
max_runtime_seconds | integer | |
budget_micros | integer | |
spent_micros | integer | |
reserved_micros | integer | |
state | string | |
end_reason optional | string | |
ended_by optional | string | |
created_at | timestamp | |
expires_at | timestamp | |
started_at optional | timestamp | |
ended_at optional | timestamp | |
kind | string | "task" (one task) or "lead". |
lead_id optional | string | |
lead_scope optional | LeadScope | |
budget | LeadBudget | |
swarm_id | string | The swarm that shows the lead in the console's swarm views (the same id). |
LeadTask
A task of a lead.
| Field | Type | Description |
|---|---|---|
id | uuid | |
lead_grant_id | uuid | |
person_id | uuid | |
state | string | |
target | string | |
target_lease_id optional | uuid | |
target_account_id optional | uuid | |
target_pool_id optional | uuid | |
engine | string | |
mode | string | |
access | string | |
credential_source optional | string | |
governance_mode | string | The mode the lead chose (observe, enforce; "" the organization's default). |
repository | string | |
ref | string | |
connection_id optional | uuid | |
cwd | string | |
brief_sha256 | string | |
brief_bytes | integer | |
max_runtime_seconds | integer | |
budget_micros | integer | |
previous_id optional | uuid | |
relation optional | string | |
lead_via | string | |
lead_agent_id optional | uuid | |
lead_client | string | |
lease_id optional | uuid | |
task_id optional | uuid | |
task_delegation_id optional | uuid | |
attempts | integer | |
last_refusal optional | string | |
end_reason optional | string | |
created_at | timestamp | |
dispatched_at optional | timestamp | |
ended_at optional | timestamp | |
queue_position optional | integer | The task's place in its lead's queue (1 first), for a queued task. |
task optional | value | The build task it became (its state, outcome, account, cost), once dispatched. |
engine_name | string | How Sandscale names Engine. |
LeadUsage
A lead grant's usage: its budget and the use of each account by its tasks.
| Field | Type | Description |
|---|---|---|
grant | LeadGrant | |
accounts | array of LeadAccountUsage | |
queued | integer |
LiveEvent
One event of the live view: a log chunk (Data, the bytes as the agent sent them, base64) or a file event.
| Field | Type | Description |
|---|---|---|
id | string | The cursor after this event (the SSE event id). |
type | string | |
seq | integer | |
data optional | string | Log. |
path optional | string | File. |
kind optional | string | |
size optional | integer | |
at optional | timestamp |
LivePage
One page of the live view.
| Field | Type | Description |
|---|---|---|
events | array of LiveEvent | |
cursor | string | Where the next page starts (also the last event's ID). |
more | boolean | Set when more events are waiting. |
state | string | |
closed optional | string | Set when the live view ends: the task ended (task_ended) or no longer holds. A client stops then. |
takeover optional | TaskTakeover |
TakeoverAnswer
TakeoverAnswer answers a take-over.
| Field | Type | Description |
|---|---|---|
takeover | TaskTakeover | |
task | value | |
terminal | TakeoverTerminal |
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).
| Field | Type | Description |
|---|---|---|
workspace_id | uuid | |
directory | string | |
web_terminal | string | |
ssh_certificate | string |
TaskBranch
The branch and pull request opened from a task's result.
| Field | Type | Description |
|---|---|---|
connection_id | uuid | |
repository | string | |
branch | string | |
commit | string | |
pull_request | integer | |
url | string | |
created_at | timestamp | |
created_by | uuid | |
replayed | boolean | True when the branch was opened by an earlier request. |
TaskChangedFileEntry
One file of a change set in a summary (never its content).
| Field | Type | Description |
|---|---|---|
path | string | |
status | string | |
executable | boolean | |
bytes | integer | |
sha256 optional | string | |
binary | boolean |
TaskCostGroup
The total of a group of tasks.
| Field | Type | Description |
|---|---|---|
id | string | |
tasks | integer | |
host_seconds | integer | |
host_micros | integer | |
model_micros | integer | |
total_micros | integer | |
total | Money | |
estimated_tasks | integer |
TaskCostTotals
The costs of the tasks created in a window, in total, per pool and (for administrators) per person.
| Field | Type | Description |
|---|---|---|
scope | string | |
since | timestamp | |
until | timestamp | |
total | TaskCostGroup | |
by_pool | array of TaskCostGroup | |
by_person optional | array of TaskCostGroup | |
truncated | boolean | |
note | string |
TaskCredential
A person's stored vendor credential as the routes show it: never its value, not even a part of it.
| Field | Type | Description |
|---|---|---|
id | uuid | |
vendor | string | |
credential_type | string | |
engines | array of string | The engines of the registry that use this vendor. |
created_at | timestamp | |
updated_at | timestamp | |
last_used_at optional | timestamp |
TaskFileView
One file of a running task's directory.
| Field | Type | Description |
|---|---|---|
path | string | |
size | integer | |
binary | boolean | |
executable | boolean | |
content optional | string | The 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).
| Field | Type | Description |
|---|---|---|
lease_id | uuid | |
mode | string | |
cwd | string | |
engine | string | |
start | string | Start names the only way to start it. |
TaskPage
One page of a task list, newest first.
| Field | Type | Description |
|---|---|---|
tasks | array of value | |
next_cursor optional | string | |
scope | string | |
settings | TaskSettings |
TaskResult
A task's result as the routes show it.
| Field | Type | Description |
|---|---|---|
task_id | uuid | |
state | string | |
refusal_reason optional | string | |
refusal_detail optional | string | |
refused_by optional | string | |
base_sha256 | string | |
change_sha256 optional | string | |
files | integer | |
added | integer | |
modified | integer | |
deleted | integer | |
content_bytes | integer | |
excluded | array of Excluded | |
created_at | timestamp | |
expires_at | timestamp | |
result_deleted | boolean | |
branch optional | TaskBranch | |
changes optional | array of TaskChangedFileEntry |
TaskSettings
The deployment's settings a client shows next to tasks, read only.
| Field | Type | Description |
|---|---|---|
branch_prefix | string | SCM write mode's branch prefix (NI_AUTH_SCM_WRITE_BRANCH_PREFIX); a task's branch is TaskBranchPattern with the task's ID. |
task_branch_pattern | string | |
queue_max_seconds | integer | |
auto_lease_linger_seconds | integer |
TaskTakeover
A take-over of a task.
| Field | Type | Description |
|---|---|---|
id | uuid | |
task_id | uuid | |
person_id | uuid | |
mode | string | |
state | string | Open, handed_back or closed (the task ended while taken over). |
directory | string | |
taken_at | timestamp | |
ended_at optional | timestamp | |
handback optional | string | |
close_reason optional | string |
TaskTree
One directory of a running task's directory.
| Field | Type | Description |
|---|---|---|
path | string | |
entries | array of TaskTreeEntry | |
hidden | integer | Hidden counts the entries left out (the deny-list, the engine's state, invalid names). |
truncated | boolean |
TaskTreeEntry
One entry of a directory of the task's directory.
| Field | Type | Description |
|---|---|---|
name | string | |
type | string | |
size | integer | |
executable optional | boolean |
Worker
One of the person's cloud agent workspaces: an active lease with a host.
| Field | Type | Description |
|---|---|---|
lease_id | uuid | |
holder_id | uuid | |
workspace_id | uuid | |
pool_id | uuid | |
pool_name | string | |
engines | array of string | |
account optional | WorkerAccount | |
state | string | |
current_task optional | WorkerTask | |
covered | boolean | |
expires_at | timestamp | |
hard_expires_at | timestamp | |
engine_names | array of string | How Sandscale names Engines, in the same order. |
WorkerAccount
The agent account bound to a worker.
| Field | Type | Description |
|---|---|---|
id | uuid | |
label | string | |
type | string | |
vendor | string | |
engine optional | string | |
binding_id | uuid | |
signin_state | string |
WorkerTask
The task a worker runs now.
| Field | Type | Description |
|---|---|---|
id | uuid | |
state | string | |
engine | string | |
started_at optional | timestamp | |
lead_task_id optional | uuid |
Money
An amount in US dollars: USD exactly (six decimals, for clients that compute), and Display as people see it. Display has two decimals ("$1,234.56"), "under $0.01" for an amount above zero that rounds below a cent, or the reason there is no amount.
| Field | Type | Description |
|---|---|---|
usd | string | |
display | string |
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).
| Field | Type | Description |
|---|---|---|
budget_micros | integer | |
committed_micros | integer | |
spent_micros | integer | |
active_task_delegations | integer |
LeadScope
What a lead grant covers. The person's device proved exactly this.
| Field | Type | Description |
|---|---|---|
engines | array of string | Engines the lead's tasks may run (at least one, of the build task registry). |
workspace_ids optional | array of string | WorkspaceIDs, 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 optional | array of string | |
pool_ids optional | array of string | |
repositories | array of string | Repositories the lead's tasks may take as their source ("owner/name"; at least one). |
modes | array of string | Modes (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. |
access | array of string | |
task_budget_micros | integer | The most model budget one task may take of the grant's budget. |
max_parallel | integer | How 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.
| Field | Type | Description |
|---|---|---|
reason | string | |
files | integer |
LeadDispatchBody
| Field | Type | Description |
|---|---|---|
target | string | |
lease_id | string | |
account_id | string | |
pool_id | string | |
engine | string | |
mode | string | |
access | string | |
credential_source | string | |
repository | string | |
ref | string | |
connection_id | string | |
cwd | string | |
brief | string | |
max_runtime_seconds | integer | |
budget_micros | integer | |
governance_mode | string |
LeadMoveBody
| Field | Type | Description |
|---|---|---|
target | string | |
lease_id | string | |
account_id | string | |
pool_id | string |
buildPoolTaskStartBody
| Field | Type | Description |
|---|---|---|
task_delegation_id | string | |
mode | string | |
task | string | |
cwd | string | |
max_runtime_seconds | integer | |
access | string | The model access (gateway, the default, or vendor_account) and CredentialSource where a vendor_account task's credential comes from (organization or person). |
credential_source | string | |
source optional | v1.buildTaskSourceBody | The repository and ref delivered to the task's directory. |
governance_mode | string | Observe or enforce ("" the organization's default; engine profiles). |
pool_id | string | |
size | string | |
keep_lease | boolean |
buildTaskCredentialBody
| Field | Type | Description |
|---|---|---|
credential_type | string | |
secret | string |
buildTaskSourceBody
| Field | Type | Description |
|---|---|---|
repository | string | |
ref | string | |
connection_id | string |
buildTaskStartBody
| Field | Type | Description |
|---|---|---|
task_delegation_id | string | |
mode | string | |
task | string | |
cwd | string | |
max_runtime_seconds | integer | |
access | string | The model access (gateway, the default, or vendor_account) and CredentialSource where a vendor_account task's credential comes from (organization or person). |
credential_source | string | |
source optional | v1.buildTaskSourceBody | The repository and ref delivered to the task's directory. |
governance_mode | string | Observe 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.