> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
{
  "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).