# OpenHands task controls and events

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 task controls

POST /agent/tasks/steer will require task_id (UUID) and a nonblank prompt of at most 8192 UTF-8 bytes. POST /agent/tasks/pause and POST /agent/tasks/resume will require task_id and no prompt. All three will require sandboxes:write, ai_chat:use and the task owner. A 202 response will return the task object (id, session_id, stream_id, status). Pause will wait for the current model call. Watch the events for the queued result. Never retry a follow-up automatically.

## GET /agent/tasks/output

This route will require sandboxes:write and the query parameter task_id (UUID). The after parameter will be an optional integer of 0 or more, default 0. A 200 application/x-ndjson response will return retained exec stdout and stderr chunks with seq and base64 data, then an exit event. Decoded stdout will contain task_event, task_status or task_error NDJSON. Events above 16 KiB will become notices. Planned limits: 512 KiB of task output. Readers will rotate at 110 seconds. Reconnect with the last sequence number. Disconnecting will not cancel work. A task_id that is not the current task will return 409 sandbox_agent_session_changed.

## Refusals and feature availability

While the feature is off, steer, pause and resume will return 503 sandbox_agent_unavailable. A caller without ai_chat:use will receive 403 permission_required. A task_id that does not match the current task will return 409 sandbox_agent_session_changed for output or DELETE. Other responses will be 400, 401, 404, 409, 429 sandbox_model_limit and 503 sandboxes_unavailable. Check GET /agent for task capability. Saved server reads and output will stay available after the feature is turned off. No single feature-off response will cover every OpenHands read.

## Related pages

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

On this page and page tools