Skip to content

Commit 5dae689

Browse files
neubigopenhands-agent
neubig
and
openhands-agent
authored
docs: Update Cloud API documentation to use V1 endpoint (OpenHands#349)
* 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@all-hands.dev> * 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@all-hands.dev> * docs: Fix indentation in Tab components Fix indentation issues with </Tab> closing tags (4 spaces -> 2 spaces), <Tab> 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@all-hands.dev> --------- Co-authored-by: openhands <openhands@all-hands.dev>
1 parent 0a68977 commit 5dae689

1 file changed

Lines changed: 202 additions & 21 deletions

File tree

‎openhands/usage/cloud/cloud-api.mdx‎

Lines changed: 202 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,206 @@ To use the OpenHands Cloud API, you'll need to generate an API key:
1717
4. Give your key a descriptive name (Example: "Development" or "Production") and select `Create`.
1818
5. Copy the generated API key and store it securely. It will only be shown once.
1919

20-
## API Usage Example
20+
## API Usage Example (V1)
2121

2222
### Starting a New Conversation
2323

2424
To start a new conversation with OpenHands to perform a task,
25-
you'll need to make a POST request to the conversation endpoint.
25+
make a POST request to the V1 app-conversations endpoint.
26+
27+
<Tabs>
28+
<Tab title="cURL">
29+
```bash
30+
curl -X POST "https://app.all-hands.dev/api/v1/app-conversations" \
31+
-H "Authorization: Bearer YOUR_API_KEY" \
32+
-H "Content-Type: application/json" \
33+
-d '{
34+
"initial_message": {
35+
"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."}]
36+
},
37+
"selected_repository": "yourusername/your-repo"
38+
}'
39+
```
40+
</Tab>
41+
<Tab title="Python (with requests)">
42+
```python
43+
import requests
44+
45+
api_key = "YOUR_API_KEY"
46+
url = "https://app.all-hands.dev/api/v1/app-conversations"
47+
48+
headers = {
49+
"Authorization": f"Bearer {api_key}",
50+
"Content-Type": "application/json"
51+
}
52+
53+
data = {
54+
"initial_message": {
55+
"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."}]
56+
},
57+
"selected_repository": "yourusername/your-repo"
58+
}
59+
60+
response = requests.post(url, headers=headers, json=data)
61+
result = response.json()
62+
63+
# The response contains a start task with the conversation ID
64+
conversation_id = result.get("app_conversation_id") or result.get("id")
65+
print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation_id}")
66+
print(f"Status: {result['status']}")
67+
```
68+
</Tab>
69+
<Tab title="TypeScript/JavaScript (with fetch)">
70+
```typescript
71+
const apiKey = "YOUR_API_KEY";
72+
const url = "https://app.all-hands.dev/api/v1/app-conversations";
73+
74+
const headers = {
75+
"Authorization": `Bearer ${apiKey}`,
76+
"Content-Type": "application/json"
77+
};
78+
79+
const data = {
80+
initial_message: {
81+
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." }]
82+
},
83+
selected_repository: "yourusername/your-repo"
84+
};
85+
86+
async function startConversation() {
87+
try {
88+
const response = await fetch(url, {
89+
method: "POST",
90+
headers: headers,
91+
body: JSON.stringify(data)
92+
});
93+
94+
const result = await response.json();
95+
96+
// The response contains a start task with the conversation ID
97+
const conversationId = result.app_conversation_id || result.id;
98+
console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversationId}`);
99+
console.log(`Status: ${result.status}`);
100+
101+
return result;
102+
} catch (error) {
103+
console.error("Error starting conversation:", error);
104+
}
105+
}
106+
107+
startConversation();
108+
```
109+
</Tab>
110+
</Tabs>
111+
112+
#### Response
113+
114+
The API will return a JSON object with details about the conversation start task:
115+
116+
```json
117+
{
118+
"id": "550e8400-e29b-41d4-a716-446655440000",
119+
"status": "WORKING",
120+
"app_conversation_id": "660e8400-e29b-41d4-a716-446655440001",
121+
"sandbox_id": "sandbox-abc123",
122+
"created_at": "2025-01-15T10:30:00Z"
123+
}
124+
```
125+
126+
The `status` field indicates the current state of the conversation startup process:
127+
- `WORKING` - Initial processing
128+
- `WAITING_FOR_SANDBOX` - Waiting for sandbox to be ready
129+
- `PREPARING_REPOSITORY` - Cloning and setting up the repository
130+
- `READY` - Conversation is ready to use
131+
- `ERROR` - An error occurred during startup
132+
133+
You may receive an authentication error if:
134+
135+
- You provided an invalid API key.
136+
- You provided the wrong repository name.
137+
- You don't have access to the repository.
138+
139+
### Streaming Conversation Start (Optional)
140+
141+
For real-time updates during conversation startup, you can use the streaming endpoint:
142+
143+
```bash
144+
curl -X POST "https://app.all-hands.dev/api/v1/app-conversations/stream-start" \
145+
-H "Authorization: Bearer YOUR_API_KEY" \
146+
-H "Content-Type: application/json" \
147+
-d '{
148+
"initial_message": {
149+
"content": [{"type": "text", "text": "Your task description here"}]
150+
},
151+
"selected_repository": "yourusername/your-repo"
152+
}'
153+
```
154+
155+
#### Streaming Response
156+
157+
The endpoint streams a JSON array incrementally. Each element represents a status update:
158+
159+
```json
160+
[
161+
{"id": "550e8400-e29b-41d4-a716-446655440000", "status": "WORKING", "created_at": "2025-01-15T10:30:00Z"},
162+
{"id": "550e8400-e29b-41d4-a716-446655440000", "status": "WAITING_FOR_SANDBOX", "created_at": "2025-01-15T10:30:00Z"},
163+
{"id": "550e8400-e29b-41d4-a716-446655440000", "status": "PREPARING_REPOSITORY", "created_at": "2025-01-15T10:30:00Z"},
164+
{"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"}
165+
]
166+
```
167+
168+
Each update is streamed as it occurs, allowing you to provide real-time feedback to users about the conversation startup progress.
169+
170+
## Rate Limits
171+
172+
If you have too many conversations running at once, older conversations will be paused to limit the number of concurrent conversations.
173+
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).
174+
175+
---
176+
177+
## Migrating from V0 to V1 API
178+
179+
<Warning>
180+
The V0 API (`/api/conversations`) is deprecated and scheduled for removal on **April 1, 2026**.
181+
Please migrate to the V1 API (`/api/v1/app-conversations`) as soon as possible.
182+
</Warning>
183+
184+
### Key Differences
185+
186+
| Feature | V0 API | V1 API |
187+
|---------|--------|--------|
188+
| Endpoint | `POST /api/conversations` | `POST /api/v1/app-conversations` |
189+
| Message format | `initial_user_msg` (string) | `initial_message.content` (array of content objects) |
190+
| Repository field | `repository` | `selected_repository` |
191+
| Response | Immediate `conversation_id` | Start task with `status` and eventual `app_conversation_id` |
192+
193+
### Migration Steps
194+
195+
1. **Update the endpoint URL**: Change from `/api/conversations` to `/api/v1/app-conversations`
196+
197+
2. **Update the request body**:
198+
- Change `repository` to `selected_repository`
199+
- Change `initial_user_msg` (string) to `initial_message` (object with content array):
200+
```json
201+
// V0 format
202+
{ "initial_user_msg": "Your message here" }
203+
204+
// V1 format
205+
{ "initial_message": { "content": [{"type": "text", "text": "Your message here"}] } }
206+
```
207+
208+
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.
209+
210+
---
211+
212+
## Legacy API (V0) - Deprecated
213+
214+
<Warning>
215+
The V0 API is deprecated since version 1.0.0 and will be removed on **April 1, 2026**.
216+
New integrations should use the V1 API documented above.
217+
</Warning>
218+
219+
### Starting a New Conversation (V0)
26220

27221
<Tabs>
28222
<Tab title="cURL">
@@ -59,9 +253,9 @@ you'll need to make a POST request to the conversation endpoint.
59253
print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['conversation_id']}")
60254
print(f"Status: {conversation['status']}")
61255
```
62-
</Tab>
63-
<Tab title="TypeScript/JavaScript (with fetch)">
64-
```typescript
256+
</Tab>
257+
<Tab title="TypeScript/JavaScript (with fetch)">
258+
```typescript
65259
const apiKey = "YOUR_API_KEY";
66260
const url = "https://app.all-hands.dev/api/conversations";
67261

@@ -85,7 +279,7 @@ you'll need to make a POST request to the conversation endpoint.
85279

86280
const conversation = await response.json();
87281

88-
console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`);
282+
console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.conversation_id}`);
89283
console.log(`Status: ${conversation.status}`);
90284

91285
return conversation;
@@ -99,24 +293,11 @@ you'll need to make a POST request to the conversation endpoint.
99293
</Tab>
100294
</Tabs>
101295

102-
#### Response
103-
104-
The API will return a JSON object with details about the created conversation:
296+
#### Response (V0)
105297

106298
```json
107299
{
108300
"status": "ok",
109-
"conversation_id": "abc1234",
301+
"conversation_id": "abc1234"
110302
}
111303
```
112-
113-
You may receive an `AuthenticationError` if:
114-
115-
- You provided an invalid API key.
116-
- You provided the wrong repository name.
117-
- You don't have access to the repository.
118-
119-
## Rate Limits
120-
121-
If you have too many conversations running at once, older conversations will be paused to limit the number of concurrent conversations.
122-
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).

0 commit comments

Comments
 (0)