From e0e1e80f0ec3b39014846068437b5b97108d0cb9 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 28 Apr 2026 18:02:55 +0000
Subject: [PATCH] docs: Add send-message REST endpoint documentation

Add documentation for the new POST /api/v1/app-conversations/{id}/send-message
endpoint that allows sending follow-up messages to conversations without
a WebSocket connection.

Includes:
- Request/response format examples
- Prerequisites (sandbox must be RUNNING)
- Error response codes
- Alternative approaches (WebSocket, direct agent server API)
- Design note about being a thin proxy

Related to: OpenHands/OpenHands#14182

Co-authored-by: openhands <openhands@all-hands.dev>
---
 openhands/usage/api/v1.mdx | 60 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/openhands/usage/api/v1.mdx b/openhands/usage/api/v1.mdx
index 52e10fa90..8b15722f1 100644
--- a/openhands/usage/api/v1.mdx
+++ b/openhands/usage/api/v1.mdx
@@ -22,9 +22,10 @@ These endpoints back the current Web UI and are intended for newer integrations.
 
 The V1 API is organized around a few core concepts:
 
-- **App conversations**: create/list conversations and access conversation metadata.
+- **App conversations**: create/list conversations, access conversation metadata, and send follow-up messages.
   - <code>POST /api/v1/app-conversations</code>
   - <code>GET /api/v1/app-conversations</code>
+  - <code>POST /api/v1/app-conversations/{id}/send-message</code>
 
 - **Sandboxes**: list/start/pause/resume the execution environments that power conversations.
   - <code>GET /api/v1/sandboxes/search</code>
@@ -35,3 +36,60 @@ The V1 API is organized around a few core concepts:
 - **Sandbox specs**: list the available sandbox “templates” (e.g., Docker image presets).
   - <code>GET /api/v1/sandbox-specs/search</code>
 
+
+## Sending messages to conversations
+
+The <code>POST /api/v1/app-conversations/{id}/send-message</code> 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 <code>POST /api/v1/sandboxes/{sandbox_id}/resume</code> first.
+- If the sandbox is **STARTING**, wait for it to reach the RUNNING state.
+
+### Request
+
+```json
+{
+  "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
+
+```json
+{
+  "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 <code>GET /api/v1/app-conversations/{id}</code>.
+
+<Note>
+  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.
+</Note>