Cloud API

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:

Log in to your OpenHands Cloud account.
Navigate to the Settings page.
Select the API Keys tab.
Click Create API Key.
Give your key a descriptive name (Example: “Development” or “Production”) and select Create.
Copy the generated API key and store it securely. It will only be shown once.

API Usage

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.

Request Parameters

Parameter	Type	Required	Description
`initial_user_msg`	string	Yes	The initial message to start the conversation.
`repository`	string	No	Git repository name to provide context in the format `owner/repo`. You must have access to the repo.

Examples

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.

Retrieving Conversation Status

You can check the status of a conversation by making a GET request to the conversation endpoint.

Endpoint

GET https://app.all-hands.dev/api/conversations/{conversation_id}

Example

cURL

Response

The response is formatted as follows:

{
  "conversation_id":"abc1234",
  "title":"Update README.md",
  "created_at":"2025-04-29T15:13:51.370706Z",
  "last_updated_at":"2025-04-29T15:13:57.199210Z",
  "status":"RUNNING",
  "selected_repository":"yourusername/your-repo",
  "trigger":"gui"
}

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.

OpenHands Cloud

Run OpenHands on Your Own

Customizations & Settings

Tips and Tricks

Troubleshooting & Feedback

OpenHands Developers

Obtaining an API Key

API Usage

Starting a New Conversation

Request Parameters

Examples

Response

Retrieving Conversation Status

Endpoint

Example

Response

Rate Limits

OpenHands Cloud

Run OpenHands on Your Own

Customizations & Settings

Tips and Tricks

Troubleshooting & Feedback

OpenHands Developers

​Obtaining an API Key

​API Usage

​Starting a New Conversation

​Request Parameters

​Examples

​Response

​Retrieving Conversation Status

​Endpoint

​Example

​Response

​Rate Limits

Obtaining an API Key

API Usage

Starting a New Conversation

Request Parameters

Examples

Response

Retrieving Conversation Status

Endpoint

Example

Response

Rate Limits