Cloud API

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.

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 account.
2. Navigate to the 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.

cURL

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"
  }'

Python (with requests)

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']}")

TypeScript/JavaScript (with fetch)

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();

Response

The API will return a JSON object with details about the created conversation:

{
  "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 [e-mail].