REST API (V1)

Overview of the current V1 REST endpoints used by the Web app.

OpenHands is in a transition period: legacy (V0) endpoints still exist alongside the new /api/v1 endpoints.

If you need the legacy OpenAPI reference, see the Legacy (V0) section in the Web tab.

Overview

OpenHands V1 REST endpoints are mounted under:

• /api/v1

These endpoints back the current Web UI and are intended for newer integrations.

Key resources

The V1 API is organized around a few core concepts:

• App conversations: create/list conversations, access conversation metadata, and send follow-up messages.

  • POST /api/v1/app-conversations
  • GET /api/v1/app-conversations
  • POST /api/v1/app-conversations//send-message

• Sandboxes: list/start/pause/resume the execution environments that power conversations.

  • GET /api/v1/sandboxes/search
  • POST /api/v1/sandboxes
  • POST /api/v1/sandboxes//pause
  • POST /api/v1/sandboxes//resume

• Sandbox specs: list the available sandbox “templates” (e.g., Docker image presets).

  • GET /api/v1/sandbox-specs/search

Sending messages to conversations

The POST /api/v1/app-conversations//send-message endpoint allows sending follow-up messages to a running conversation without establishing a WebSocket connection.

Prerequisites

• The sandbox must be in RUNNING state.
• If the sandbox is PAUSED, call POST /api/v1/sandboxes//resume first.
• If the sandbox is STARTING, wait for it to reach the RUNNING state.

Request

{
  "role": "user",
  "content": [{"type": "text", "text": "Your message here"}],
  "run": true
}

Field	Type	Required	Description
role	string	No	Always "user" (default).
content	array	Yes	List of content blocks (text and/or image).
run	boolean	No	Whether the agent should continue execution after receiving the message (default: true).

Response

{
  "success": true,
  "sandbox_status": "RUNNING",
  "message": null
}

Error responses

Status	Description
404	Conversation or sandbox not found.
409	Sandbox is not running (PAUSED, STARTING, STOPPING). Resume it first.
410	Conversation is archived (sandbox no longer exists).
503	Sandbox is in error state or agent server is unavailable.

Alternative approaches

This endpoint is a convenience wrapper. You can also interact with the agent server directly:

1. WebSocket: Connect to the agent server’s WebSocket endpoint for real-time bidirectional communication.
2. Agent Server REST API: Call the agent server’s REST endpoints directly using the conversation_url from GET /api/v1/app-conversations/.

This endpoint is intentionally a thin proxy that forwards messages to the agent server without additional processing logic. Any custom processing (validation, transformation, side effects) should be implemented via webhook callbacks.