Cloud Computers
The machine each AI team runs on.
Get an AI team's Cloud Computer
/v1/teams/{team_id}/computercompute:readIts size, power state, pause and update state.
team_idstringrequiredAn AI team id.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Computer object.
200The Cloud Computer.
OtherAn RFC 9457 problem.
Start the Cloud Computer
/v1/teams/{team_id}/computer/startcompute:wakeWakes a sleeping machine (needs compute:wake), or starts a stopped one (also needs
compute:rebuild). Returns an operation to follow, or the computer when it already runs.
Requires an Idempotency-Key.
team_idstringrequiredAn AI team id.
Idempotency-KeystringrequiredRequired here. The same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422; while the first request is still running, 409idempotency_in_progress.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Computer object.
200Already running; nothing to do.
202Started. Follow the operation.
OtherAn RFC 9457 problem.
Stop the Cloud Computer
/v1/teams/{team_id}/computer/stopcompute:rebuildA full stop (not a sleep). The team's files stay. Refused with 409 computer_busy while a
session runs, unless force is true. Requires an Idempotency-Key.
team_idstringrequiredAn AI team id.
Idempotency-KeystringrequiredRequired here. The same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422; while the first request is still running, 409idempotency_in_progress.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
forcebooleanStop even while sessions run (they stop with it).
Returns a Computer object.
200Not running; nothing to do.
202Stopping. Follow the operation.
OtherAn RFC 9457 problem.
Update the Cloud Computer
/v1/teams/{team_id}/computer/updatecompute:rebuildRebuilds the machine on the current system software, keeping every file. restart: true
restarts it even when it is current, and is required while sessions run (409
computer_busy otherwise). While another operation, an update or a resize runs, the
answer is 409 operation_conflict. Requires an Idempotency-Key.
team_idstringrequiredAn AI team id.
Idempotency-KeystringrequiredRequired here. The same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422; while the first request is still running, 409idempotency_in_progress.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
restartbooleanRestart even when the machine is current; needed while sessions run.
Returns a Computer object.
200Nothing started. Already up to date, or nothing to update now (
update_availablesays whether an update is pending).202Updating. Follow the operation.
OtherAn RFC 9457 problem.
Resize the Cloud Computer
/v1/teams/{team_id}/computer/resizecompute:resizeMoves the team to a Boost tier the organization owns a free slot of (409 when it has none),
or back to standard. Requires an Idempotency-Key.
A larger tier on a live machine is a 202 operation that succeeds once the machine runs the
new size. A smaller tier on a running machine applies at its next restart, as in HQ: the
answer is 200 with the computer, change_pending: true, and no operation; send
POST …/computer/update with restart: true to apply it now. A stopped machine gets the
new size at its next start (also 200). While another operation, an update or a resize
runs, the answer is 409 operation_conflict, with operation naming the blocking
operation when it was started over the API.
team_idstringrequiredAn AI team id.
Idempotency-KeystringrequiredRequired here. The same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422; while the first request is still running, 409idempotency_in_progress.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
tierstringrequiredOne of
standard,boost,boost_pro,boost_max.
Returns a Computer object.
200Nothing to follow. Already on this tier, or the new tier is recorded and applies at the next restart or start (
change_pending).202Resizing. Follow the operation.
OtherAn RFC 9457 problem.
Unpause the Cloud Computer
/v1/teams/{team_id}/computer/unpausecompute:unpauseClears an abuse pause. The machine comes back with its next session or wake.
team_idstringrequiredAn AI team id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Computer object.
200The computer.
OtherAn RFC 9457 problem.
Objects
Computer
objectstringteamstringstatestringOpen-ended: running, starting, suspending, suspended, resuming, stopping, stopped, resizing, updating, error.
tierstringboost_sourcestring or nullmax_sessionsintegerpausedbooleanpaused_atstring or nullresize_statestringchange_pendingbooleanTrue while the machine still has the size of an earlier tier. A move to a smaller tier on a running Cloud Computer applies at its next restart (send POST /v1/teams/{team_id}/computer/update with restart: true to apply it now); a stopped one gets the new size at its next start. A sleeping one wakes on its current size; a bigger tier then applies once it is running, a smaller one at its next restart.
update_statestringupdate_availableboolean or nulllast_updated_atstring or null