OpenHands/docs/modules/usage/cloud/cloud-api.md

OpenHands Cloud API

OpenHands Cloud provides a REST API that allows you to programmatically interact with the service. This is useful if you easily want to kick off your own jobs from your programs in a flexible way.

This guide explains how to obtain an API key and use the API to start conversations. For more detailed information about the API, 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 page
3. Locate the "API Keys" section
4. Click "Generate New Key"
5. Give your key a descriptive name (e.g., "Development", "Production")
6. 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 performing 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['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 also receive an AuthenticationError if:

1. You provided an invalid API key
2. You provided the wrong repo name
3. You don't have access to the repo

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

curl -X GET "https://app.all-hands.dev/api/conversations/{conversation_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

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.