AI Workforce OneHQDocs

Cloud Computers

The machine each AI team runs on.

Get an AI team's Cloud Computer

GET/v1/teams/{team_id}/computer
Permission compute:read

Its size, power state, pause and update state.

Path parameters
team_idstringrequired

An AI team id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The Cloud Computer.

Other

An RFC 9457 problem.

Start the Cloud Computer

POST/v1/teams/{team_id}/computer/start
Permission compute:wake

Wakes 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.

Path parameters
team_idstringrequired

An AI team id.

Headers
Idempotency-Keystringrequired

Required 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, 409 idempotency_in_progress.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

Already running; nothing to do.

202

Started. Follow the operation.

Other

An RFC 9457 problem.

Stop the Cloud Computer

POST/v1/teams/{team_id}/computer/stop
Permission compute:rebuild

A 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.

Path parameters
team_idstringrequired

An AI team id.

Headers
Idempotency-Keystringrequired

Required 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, 409 idempotency_in_progress.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
forceboolean

Stop even while sessions run (they stop with it).

Returns a Computer object.

Responses
200

Not running; nothing to do.

202

Stopping. Follow the operation.

Other

An RFC 9457 problem.

Update the Cloud Computer

POST/v1/teams/{team_id}/computer/update
Permission compute:rebuild

Rebuilds 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.

Path parameters
team_idstringrequired

An AI team id.

Headers
Idempotency-Keystringrequired

Required 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, 409 idempotency_in_progress.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
restartboolean

Restart even when the machine is current; needed while sessions run.

Returns a Computer object.

Responses
200

Nothing started. Already up to date, or nothing to update now (update_available says whether an update is pending).

202

Updating. Follow the operation.

Other

An RFC 9457 problem.

Resize the Cloud Computer

POST/v1/teams/{team_id}/computer/resize
Permission compute:resize

Moves 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.

Path parameters
team_idstringrequired

An AI team id.

Headers
Idempotency-Keystringrequired

Required 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, 409 idempotency_in_progress.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
tierstringrequired

One of standard, boost, boost_pro, boost_max.

Returns a Computer object.

Responses
200

Nothing to follow. Already on this tier, or the new tier is recorded and applies at the next restart or start (change_pending).

202

Resizing. Follow the operation.

Other

An RFC 9457 problem.

Unpause the Cloud Computer

POST/v1/teams/{team_id}/computer/unpause
Permission compute:unpause

Clears an abuse pause. The machine comes back with its next session or wake.

Path parameters
team_idstringrequired

An AI team id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The computer.

Other

An RFC 9457 problem.

Objects

Computer

Attributes
objectstring
teamstring
statestring

Open-ended: running, starting, suspending, suspended, resuming, stopping, stopped, resizing, updating, error.

tierstring
boost_sourcestring or null
max_sessionsinteger
pausedboolean
paused_atstring or null
resize_statestring
change_pendingboolean

True 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_statestring
update_availableboolean or null
last_updated_atstring or null