AI Workforce OneHQDocs

Operations

Follow a Cloud Computer start, stop, update or resize until it finishes.

Starting, stopping, updating or resizing an AI team's Cloud Computer takes from seconds to minutes. These requests answer 202 Accepted with an operation, and you poll it until it is done.

curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_…/computer/start \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
{
  "object": "operation",
  "id": "op_…",
  "kind": "computer.start",
  "status": "running",
  "target": { "type": "team", "id": "team_…" },
  "requested": {},
  "error": null,
  "created_by": { "kind": "user_key", "key": "key_…", "label": "jean@example.com" },
  "created_at": "2026-11-02T09:00:00Z",
  "updated_at": "2026-11-02T09:00:00Z",
  "completed_at": null
}

Then GET /v1/operations/{operation_id}. While it runs, the answer carries Retry-After: 5: poll no faster than that.

statusMeaning
queued, runningStill going.
succeededDone: the machine is running (start), stopped (stop), on the current system software (update) or on the new size (resize).
failederror.code and error.message say why, for example timeout (it did not finish within 30 minutes).
canceledSomething else replaced it.

GET /v1/operations lists the operations of the AI teams your key can see, newest first. An operation is kept for 30 days.

One at a time per AI team

A team runs one operation at a time. Asking for another while one runs is refused with 409 operation_conflict, and operation names the one in progress so you can wait for it. The same 409 operation_conflict answers while the machine is being changed from HQ (an update or a resize someone started there, or a scheduled update); then there is no operation to name, so retry after a minute.

A request that is refused (a permission, no Boost slot to assign, a conflict) creates no operation and sends no operation.failed webhook.

Nothing to do

A start on a machine that is already running, or a resize to the size it already has, answers 200 with the Cloud Computer and no operation. So does an update that has nothing to start now (the machine is current, or it is stopped and boots the current system software at its next start); update_available on the Cloud Computer says whether an update is still pending.

Resizing to a smaller tier

Moving a running machine to a smaller tier does not interrupt it: the new size applies at its next restart, as in HQ. The resize answers 200 with the Cloud Computer, tier set to the new tier and change_pending: true, and no operation. To apply it now, send POST /v1/teams/{team_id}/computer/update with {"restart": true}. A stopped machine gets the new size when it next starts.

Stop and update refuse while sessions run

stop and update refuse with 409 computer_busy while sessions are running on the machine. Send {"force": true} (stop) or {"restart": true} (update) to go ahead and stop them.

Who may

RequestPermission
Start a sleeping machinecompute:wake
Start a stopped machine, stop, updatecompute:rebuild
Resizecompute:resize
Unpausecompute:unpause
Read operationscompute:read