mirror of
https://github.com/OpenHands/OpenHands.git
synced 2025-12-26 05:48:36 +08:00
123 lines
3.8 KiB
Plaintext
123 lines
3.8 KiB
Plaintext
---
|
|
title: Cloud API
|
|
description: OpenHands Cloud provides a REST API that allows you to programmatically interact with OpenHands.
|
|
This guide explains how to obtain an API key and use the API to start conversations and retrieve their status.
|
|
---
|
|
|
|
For the available API endpoints, refer to the
|
|
[OpenHands API Reference](https://docs.all-hands.dev/api-reference).
|
|
|
|
## Obtaining an API Key
|
|
|
|
To use the OpenHands Cloud API, you'll need to generate an API key:
|
|
|
|
1. Log in to your [OpenHands Cloud](https://app.all-hands.dev) account.
|
|
2. Navigate to the [Settings > API Keys](https://app.all-hands.dev/settings/api-keys) page.
|
|
3. Click `Create 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
|
|
|
|
### 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](/api-reference/new-conversation).
|
|
|
|
<Tabs>
|
|
<Tab title="cURL">
|
|
```bash
|
|
curl -X POST "https://app.all-hands.dev/api/conversations" \
|
|
-H "Authorization: Bearer YOUR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
|
|
"repository": "yourusername/your-repo"
|
|
}'
|
|
```
|
|
</Tab>
|
|
<Tab title="Python (with requests)">
|
|
```python
|
|
import requests
|
|
|
|
api_key = "YOUR_API_KEY"
|
|
url = "https://app.all-hands.dev/api/conversations"
|
|
|
|
headers = {
|
|
"Authorization": f"Bearer {api_key}",
|
|
"Content-Type": "application/json"
|
|
}
|
|
|
|
data = {
|
|
"initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
|
|
"repository": "yourusername/your-repo"
|
|
}
|
|
|
|
response = requests.post(url, headers=headers, json=data)
|
|
conversation = response.json()
|
|
|
|
print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['conversation_id']}")
|
|
print(f"Status: {conversation['status']}")
|
|
```
|
|
</Tab>
|
|
<Tab title="TypeScript/JavaScript (with fetch)">
|
|
```typescript
|
|
const apiKey = "YOUR_API_KEY";
|
|
const url = "https://app.all-hands.dev/api/conversations";
|
|
|
|
const headers = {
|
|
"Authorization": `Bearer ${apiKey}`,
|
|
"Content-Type": "application/json"
|
|
};
|
|
|
|
const data = {
|
|
initial_user_msg: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
|
|
repository: "yourusername/your-repo"
|
|
};
|
|
|
|
async function startConversation() {
|
|
try {
|
|
const response = await fetch(url, {
|
|
method: "POST",
|
|
headers: headers,
|
|
body: JSON.stringify(data)
|
|
});
|
|
|
|
const conversation = await response.json();
|
|
|
|
console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`);
|
|
console.log(`Status: ${conversation.status}`);
|
|
|
|
return conversation;
|
|
} catch (error) {
|
|
console.error("Error starting conversation:", error);
|
|
}
|
|
}
|
|
|
|
startConversation();
|
|
```
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
#### Response
|
|
|
|
The API will return a JSON object with details about the created conversation:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"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).
|