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

## Related pages

[API overview](https://runzivo.dev/docs/sandboxes-devx-api/)

On this page and page tools