Documentation
OpenHands task requests
Coming soon. Planned API contract, subject to change. These features are not available yet in production.
Authentication and path
Paths follow /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}. Requests will use a bearer customer access token or a workspace API key. The sandbox and repository grants below are key permissions, not legacy scopes. A key with all:all will also work, within its creator’s current permissions. The SSH relay uses its ticket instead of a bearer token.
POST /agent/tasks
Submitting a task will require sandboxes:write, ai_chat:use, the feature turned on and a supported workspace provider. The JSON body will require session_id (sxe_ plus 24 hex characters) and a nonblank prompt of at most 8192 UTF-8 bytes. The optional model_budget_micro_usd will be a positive integer up to the configured maximum. It will be an internal cost ceiling, not a price. The design keeps provider keys outside the sandbox. Anyone with sandbox command access will also get the task’s AI access up to its budget.
GET and DELETE /agent/tasks
GET will read the latest task with sandboxes:read or sandboxes:write and return 200. DELETE will require sandboxes:write and the query parameter task_id (UUID). It will return 200 and cancel the named task and its server. POST will return 202. Each success will return id (UUID), session_id, stream_id (both sxe_ identifiers) and status (active, stopped or failed). Active will mean queued or running, not completed.
Errors and model limits
While the feature is off, POST will return 503 sandbox_agent_unavailable. A caller without ai_chat:use will receive 403 permission_required. A DELETE whose task_id is not the current task will return 409 sandbox_agent_session_changed. Other responses will be 400 invalid_request, 401, 404, 409, 429 sandbox_model_limit and 503 sandboxes_unavailable. GET /agent will report task capability as tasks_available and task_unavailable_reason. A running server alone will not enable tasks. Do not retry a task submission automatically. The internal budget will not be a new charge.