Skip to content

docs: Add send-message REST endpoint documentation #482

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
malhotra5 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Add send-message REST endpoint documentation #482

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 59 additions & 1 deletion openhands/usage/api/v1.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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 |
Copy link
Copy Markdown
Contributor

@all-hands-bot all-hands-bot Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: The description mentions "text and/or image" but only shows a text example. Consider adding an example of the image content block format:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Check this image:"},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
  ],
  "run": true
}

Or add a link to documentation that describes the content block schema in detail.

|-------|------|----------|-------------|
| `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

Copy link
Copy Markdown
Contributor

@all-hands-bot all-hands-bot Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: The error description says "Resume it first" for STARTING/STOPPING states, but the prerequisites section (line 47) correctly says to "wait" for STARTING state, not resume it. Consider clarifying:

Suggested change
| 409 | Sandbox is not running. For PAUSED state, resume it first. For STARTING state, wait for it to reach RUNNING. |

| 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

Copy link
Copy Markdown
Contributor

@all-hands-bot all-hands-bot Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: The conversation_url field is referenced but not explained. Consider either:

  • Adding a sentence explaining what this field contains (e.g., "the base URL for direct agent server API calls")
  • Linking to documentation for the GET /api/v1/app-conversations/{id} endpoint response schema
  • Or providing an example showing what a conversation_url looks like

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>.
Copy link
Copy Markdown
Contributor

@all-hands-bot all-hands-bot Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: Webhook callbacks are mentioned but not explained or linked. Consider either:

  • Linking to webhook callback documentation if it exists
  • Or briefly explaining what webhook callbacks are in this context (e.g., "via the conversation's webhook configuration")

This helps users understand how to implement custom processing without having to search for webhook documentation separately.


<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>
Loading