From 3b00e6d3e45b1a04d32d84c59f03e29e9b3c5646 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Feb 2026 21:26:28 +0000 Subject: [PATCH 1/3] docs: Update Cloud API documentation to use V1 endpoint - Add V1 API documentation as the primary/recommended approach - Document the new request format (initial_message with content array) - Document the new response format (start task with status progression) - Add migration guide from V0 to V1 API - Keep V0 API documentation with deprecation warnings - Note V0 API removal scheduled for April 1, 2026 The V1 API provides better conversation lifecycle management with status updates during startup (WORKING -> READY). Co-authored-by: openhands --- openhands/usage/cloud/cloud-api.mdx | 204 +++++++++++++++++++++++++--- 1 file changed, 186 insertions(+), 18 deletions(-) diff --git a/openhands/usage/cloud/cloud-api.mdx b/openhands/usage/cloud/cloud-api.mdx index 48303680..1ca54ded 100644 --- a/openhands/usage/cloud/cloud-api.mdx +++ b/openhands/usage/cloud/cloud-api.mdx @@ -17,12 +17,193 @@ To use the OpenHands Cloud API, you'll need to generate an API key: 4. Give your key a descriptive name (Example: "Development" or "Production") and select `Create`. 5. Copy the generated API key and store it securely. It will only be shown once. -## API Usage Example +## API Usage Example (V1) ### Starting a New Conversation To start a new conversation with OpenHands to perform a task, -you'll need to make a POST request to the conversation endpoint. +make a POST request to the V1 app-conversations endpoint. + + + + ```bash + curl -X POST "https://app.all-hands.dev/api/v1/app-conversations" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "initial_message": { + "content": [{"type": "text", "text": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so."}] + }, + "selected_repository": "yourusername/your-repo" + }' + ``` + + + ```python + import requests + + api_key = "YOUR_API_KEY" + url = "https://app.all-hands.dev/api/v1/app-conversations" + + headers = { + "Authorization": f"Bearer {api_key}", + "Content-Type": "application/json" + } + + data = { + "initial_message": { + "content": [{"type": "text", "text": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so."}] + }, + "selected_repository": "yourusername/your-repo" + } + + response = requests.post(url, headers=headers, json=data) + result = response.json() + + # The response contains a start task with the conversation ID + conversation_id = result.get("app_conversation_id") or result.get("id") + print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation_id}") + print(f"Status: {result['status']}") + ``` + + + ```typescript + const apiKey = "YOUR_API_KEY"; + const url = "https://app.all-hands.dev/api/v1/app-conversations"; + + const headers = { + "Authorization": `Bearer ${apiKey}`, + "Content-Type": "application/json" + }; + + const data = { + initial_message: { + content: [{ type: "text", text: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so." }] + }, + selected_repository: "yourusername/your-repo" + }; + + async function startConversation() { + try { + const response = await fetch(url, { + method: "POST", + headers: headers, + body: JSON.stringify(data) + }); + + const result = await response.json(); + + // The response contains a start task with the conversation ID + const conversationId = result.app_conversation_id || result.id; + console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversationId}`); + console.log(`Status: ${result.status}`); + + return result; + } catch (error) { + console.error("Error starting conversation:", error); + } + } + + startConversation(); + ``` + + + +#### Response + +The API will return a JSON object with details about the conversation start task: + +```json +{ + "id": "550e8400-e29b-41d4-a716-446655440000", + "status": "WORKING", + "app_conversation_id": "660e8400-e29b-41d4-a716-446655440001", + "sandbox_id": "sandbox-abc123", + "created_at": "2025-01-15T10:30:00Z" +} +``` + +The `status` field indicates the current state of the conversation startup process: +- `WORKING` - Initial processing +- `WAITING_FOR_SANDBOX` - Waiting for sandbox to be ready +- `PREPARING_REPOSITORY` - Cloning and setting up the repository +- `READY` - Conversation is ready to use +- `ERROR` - An error occurred during startup + +You may receive an authentication error if: + +- You provided an invalid API key. +- You provided the wrong repository name. +- You don't have access to the repository. + +### Streaming Conversation Start (Optional) + +For real-time updates during conversation startup, you can use the streaming endpoint: + +```bash +curl -X POST "https://app.all-hands.dev/api/v1/app-conversations/stream-start" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "initial_message": { + "content": [{"type": "text", "text": "Your task description here"}] + }, + "selected_repository": "yourusername/your-repo" + }' +``` + +This returns a JSON array streamed incrementally, with status updates as the conversation starts up. + +## Rate Limits + +If you have too many conversations running at once, older conversations will be paused to limit the number of concurrent conversations. +If you're running into issues and need a higher limit for your use case, please contact us at [contact@all-hands.dev](mailto:contact@all-hands.dev). + +--- + +## Migrating from V0 to V1 API + + + The V0 API (`/api/conversations`) is deprecated and scheduled for removal on **April 1, 2026**. + Please migrate to the V1 API (`/api/v1/app-conversations`) as soon as possible. + + +### Key Differences + +| Feature | V0 API | V1 API | +|---------|--------|--------| +| Endpoint | `POST /api/conversations` | `POST /api/v1/app-conversations` | +| Message format | `initial_user_msg` (string) | `initial_message.content` (array of content objects) | +| Repository field | `repository` | `selected_repository` | +| Response | Immediate `conversation_id` | Start task with `status` and eventual `app_conversation_id` | + +### Migration Steps + +1. **Update the endpoint URL**: Change from `/api/conversations` to `/api/v1/app-conversations` + +2. **Update the request body**: + - Change `repository` to `selected_repository` + - Change `initial_user_msg` (string) to `initial_message` (object with content array): + ```json + // V0 format + { "initial_user_msg": "Your message here" } + + // V1 format + { "initial_message": { "content": [{"type": "text", "text": "Your message here"}] } } + ``` + +3. **Update response handling**: The V1 API returns a start task object. The conversation ID is in the `app_conversation_id` field (available when status is `READY`), or use the `id` field for the start task ID. + +--- + +## Legacy API (V0) - Deprecated + + + The V0 API is deprecated since version 1.0.0 and will be removed on **April 1, 2026**. + New integrations should use the V1 API documented above. + + +### Starting a New Conversation (V0) @@ -85,7 +266,7 @@ you'll need to make a POST request to the conversation endpoint. const conversation = await response.json(); - console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`); + console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.conversation_id}`); console.log(`Status: ${conversation.status}`); return conversation; @@ -99,24 +280,11 @@ you'll need to make a POST request to the conversation endpoint. -#### Response - -The API will return a JSON object with details about the created conversation: +#### Response (V0) ```json { "status": "ok", - "conversation_id": "abc1234", + "conversation_id": "abc1234" } ``` - -You may receive an `AuthenticationError` if: - -- You provided an invalid API key. -- You provided the wrong repository name. -- You don't have access to the repository. - -## Rate Limits - -If you have too many conversations running at once, older conversations will be paused to limit the number of concurrent conversations. -If you're running into issues and need a higher limit for your use case, please contact us at [contact@all-hands.dev](mailto:contact@all-hands.dev). From 8f0a789b96e1a3647f89d9f26e43b239588d1e81 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Feb 2026 23:30:54 +0000 Subject: [PATCH 2/3] docs: Add streaming response format example Address review comment by adding an example of the streaming response format for the /api/v1/app-conversations/stream-start endpoint. Co-authored-by: openhands --- openhands/usage/cloud/cloud-api.mdx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/openhands/usage/cloud/cloud-api.mdx b/openhands/usage/cloud/cloud-api.mdx index 1ca54ded..1cfdebfd 100644 --- a/openhands/usage/cloud/cloud-api.mdx +++ b/openhands/usage/cloud/cloud-api.mdx @@ -152,7 +152,20 @@ curl -X POST "https://app.all-hands.dev/api/v1/app-conversations/stream-start" \ }' ``` -This returns a JSON array streamed incrementally, with status updates as the conversation starts up. +#### Streaming Response + +The endpoint streams a JSON array incrementally. Each element represents a status update: + +```json +[ + {"id": "550e8400-e29b-41d4-a716-446655440000", "status": "WORKING", "created_at": "2025-01-15T10:30:00Z"}, + {"id": "550e8400-e29b-41d4-a716-446655440000", "status": "WAITING_FOR_SANDBOX", "created_at": "2025-01-15T10:30:00Z"}, + {"id": "550e8400-e29b-41d4-a716-446655440000", "status": "PREPARING_REPOSITORY", "created_at": "2025-01-15T10:30:00Z"}, + {"id": "550e8400-e29b-41d4-a716-446655440000", "status": "READY", "app_conversation_id": "660e8400-e29b-41d4-a716-446655440001", "sandbox_id": "sandbox-abc123", "created_at": "2025-01-15T10:30:00Z"} +] +``` + +Each update is streamed as it occurs, allowing you to provide real-time feedback to users about the conversation startup progress. ## Rate Limits From 20b98d998d4f15bc664ec11dda6a9065384eaaa3 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 19 Feb 2026 23:31:45 +0000 Subject: [PATCH 3/3] docs: Fix indentation in Tab components Fix indentation issues with closing tags (4 spaces -> 2 spaces), opening tags (4 spaces -> 2 spaces), and code blocks (8 spaces -> 4 spaces) in both V1 and V0 API example sections. Co-authored-by: openhands --- openhands/usage/cloud/cloud-api.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/openhands/usage/cloud/cloud-api.mdx b/openhands/usage/cloud/cloud-api.mdx index 1cfdebfd..c8e7bb6d 100644 --- a/openhands/usage/cloud/cloud-api.mdx +++ b/openhands/usage/cloud/cloud-api.mdx @@ -65,9 +65,9 @@ make a POST request to the V1 app-conversations endpoint. print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation_id}") print(f"Status: {result['status']}") ``` - - - ```typescript + + + ```typescript const apiKey = "YOUR_API_KEY"; const url = "https://app.all-hands.dev/api/v1/app-conversations"; @@ -253,9 +253,9 @@ If you're running into issues and need a higher limit for your use case, please print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['conversation_id']}") print(f"Status: {conversation['status']}") ``` - - - ```typescript + + + ```typescript const apiKey = "YOUR_API_KEY"; const url = "https://app.all-hands.dev/api/conversations";