---
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).