> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/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.openhands.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 (V1)

### Starting a New Conversation

To start a new conversation with OpenHands to perform a task,
make a POST request to the V1 app-conversations endpoint.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://app.all-hands.dev/api/v1/app-conversations" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "initial_message": {
          "content": [{"type": "text", "text": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so."}]
        },
        "selected_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/v1/app-conversations"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    data = {
        "initial_message": {
            "content": [{"type": "text", "text": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so."}]
        },
        "selected_repository": "yourusername/your-repo"
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()

    # The response contains a start task with the conversation ID
    conversation_id = result.get("app_conversation_id") or result.get("id")
    print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation_id}")
    print(f"Status: {result['status']}")
    ```
  </Tab>

  <Tab title="TypeScript/JavaScript (with fetch)">
    ```typescript theme={null}
    const apiKey = "YOUR_API_KEY";
    const url = "https://app.all-hands.dev/api/v1/app-conversations";

    const headers = {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    };

    const data = {
      initial_message: {
        content: [{ type: "text", text: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so." }]
      },
      selected_repository: "yourusername/your-repo"
    };

    async function startConversation() {
      try {
        const response = await fetch(url, {
          method: "POST",
          headers: headers,
          body: JSON.stringify(data)
        });

        const result = await response.json();

        // The response contains a start task with the conversation ID
        const conversationId = result.app_conversation_id || result.id;
        console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversationId}`);
        console.log(`Status: ${result.status}`);

        return result;
      } catch (error) {
        console.error("Error starting conversation:", error);
      }
    }

    startConversation();
    ```
  </Tab>
</Tabs>

#### Response

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

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "WORKING",
  "app_conversation_id": "660e8400-e29b-41d4-a716-446655440001",
  "sandbox_id": "sandbox-abc123",
  "created_at": "2025-01-15T10:30:00Z"
}
```

The `status` field indicates the current state of the conversation startup process:

* `WORKING` - Initial processing
* `WAITING_FOR_SANDBOX` - Waiting for sandbox to be ready
* `PREPARING_REPOSITORY` - Cloning and setting up the repository
* `SETTING_UP_SKILLS` - Configuring agent skills and tools
* `READY` - Conversation is ready to use
* `ERROR` - An error occurred during startup

You may receive an authentication error if:

* You provided an invalid API key.
* You provided the wrong repository name.
* You don't have access to the repository.

### Streaming Conversation Start (Optional)

For real-time updates during conversation startup, you can use the streaming endpoint:

```bash theme={null}
curl -X POST "https://app.all-hands.dev/api/v1/app-conversations/stream-start" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "initial_message": {
      "content": [{"type": "text", "text": "Your task description here"}]
    },
    "selected_repository": "yourusername/your-repo"
  }'
```

#### Streaming Response

The endpoint streams a JSON array incrementally. Each element represents a status update:

```json theme={null}
[
  {"id": "550e8400-e29b-41d4-a716-446655440000", "status": "WORKING", "created_at": "2025-01-15T10:30:00Z"},
  {"id": "550e8400-e29b-41d4-a716-446655440000", "status": "WAITING_FOR_SANDBOX", "created_at": "2025-01-15T10:30:00Z"},
  {"id": "550e8400-e29b-41d4-a716-446655440000", "status": "PREPARING_REPOSITORY", "created_at": "2025-01-15T10:30:00Z"},
  {"id": "550e8400-e29b-41d4-a716-446655440000", "status": "READY", "app_conversation_id": "660e8400-e29b-41d4-a716-446655440001", "sandbox_id": "sandbox-abc123", "created_at": "2025-01-15T10:30:00Z"}
]
```

Each update is streamed as it occurs, allowing you to provide real-time feedback to users about the conversation startup progress.

### Checking Conversation Status

After starting a conversation, you can check its status to monitor whether the agent has completed its task.

<Note>
  The examples below show basic polling patterns. For production use, add proper error handling,
  exponential backoff, and handle network failures gracefully.
</Note>

#### Step 1: Check Start Task Status

When you start a conversation, you receive a start task ID. Poll this endpoint until `status` becomes `READY` and `app_conversation_id` is available:

```bash theme={null}
curl -X GET "https://app.all-hands.dev/api/v1/app-conversations/start-tasks?ids=TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "READY",
  "app_conversation_id": "660e8400-e29b-41d4-a716-446655440001",
  "sandbox_id": "sandbox-abc123"
}
```

#### Step 2: Check Conversation Execution Status

Once you have the `app_conversation_id`, check whether the agent has finished its task:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://app.all-hands.dev/api/v1/app-conversations?ids=CONVERSATION_ID" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Python (with requests)">
    ```python theme={null}
    import requests

    api_key = "YOUR_API_KEY"
    conversation_id = "YOUR_CONVERSATION_ID"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    response = requests.get(
        "https://app.all-hands.dev/api/v1/app-conversations",
        headers=headers,
        params={"ids": conversation_id}
    )
    response.raise_for_status()  # Raise exception for HTTP errors
    conversations = response.json()

    if conversations:
        conv = conversations[0]
        print(f"Sandbox Status: {conv.get('sandbox_status')}")
        print(f"Execution Status: {conv.get('execution_status')}")
    else:
        print("Conversation not found")
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
[
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "sandbox_status": "RUNNING",
    "execution_status": "finished",
    "selected_repository": "yourusername/your-repo",
    "title": "Fix README"
  }
]
```

#### Status Fields

**`sandbox_status`** - The state of the sandbox environment:

* `STARTING` - Sandbox is being created. **Action:** Continue polling.
* `RUNNING` - Sandbox is active. **Action:** Check `execution_status` for task progress.
* `PAUSED` - Sandbox is paused (due to rate limits or user action). **Action:** The sandbox will resume automatically when resources are available, or resume manually via the UI.
* `ERROR` - Sandbox encountered an error. **Action:** This is a terminal state. Check conversation details in the UI for error information.
* `MISSING` - Sandbox was deleted. **Action:** This is a terminal state. Start a new conversation if needed.

**`execution_status`** - The state of the agent's task (available when sandbox is `RUNNING`):

* `idle` - Agent is ready to receive tasks. **Action:** Continue polling if task was recently submitted.
* `running` - Agent is actively working. **Action:** Continue polling.
* `paused` - Execution is paused. **Action:** Continue polling; will resume automatically.
* `waiting_for_confirmation` - Agent is waiting for user confirmation. **Action:** This is a blocking state. The agent needs user input via the UI to proceed. Your polling loop should treat this as a terminal state or alert the user.
* `finished` - Agent has completed the task. **Action:** Terminal state. Task is done successfully.
* `error` - Agent encountered an error. **Action:** Terminal state. Check conversation in UI for error details.
* `stuck` - Agent is stuck and unable to proceed. **Action:** Terminal state. Manual intervention may be required.

<Note>
  **Terminal states** that should exit your polling loop: `finished`, `error`, `stuck`, `waiting_for_confirmation`.
  The `waiting_for_confirmation` state requires user action through the UI before the agent can continue.
</Note>

#### Complete Polling Example

Here's a complete example that starts a conversation and polls until completion:

```python theme={null}
import requests
import time

api_key = "YOUR_API_KEY"
base_url = "https://app.all-hands.dev"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

# Start a conversation
print("Starting conversation...")
start_response = requests.post(
    f"{base_url}/api/v1/app-conversations",
    headers=headers,
    json={
        "initial_message": {
            "content": [{"type": "text", "text": "Your task here"}]
        },
        "selected_repository": "yourusername/your-repo"
    }
)
start_response.raise_for_status()
start_task = start_response.json()
task_id = start_task["id"]
print(f"Start task ID: {task_id}")

# Poll start task until conversation is ready (with timeout)
conversation_id = None
max_attempts = 60  # 5 minutes with 5-second intervals
attempts = 0
while not conversation_id and attempts < max_attempts:
    task_response = requests.get(
        f"{base_url}/api/v1/app-conversations/start-tasks",
        headers=headers,
        params={"ids": task_id}
    )
    task_response.raise_for_status()
    tasks = task_response.json()
    
    if tasks and tasks[0].get("status") == "READY":
        conversation_id = tasks[0].get("app_conversation_id")
        print(f"Conversation ready: {base_url}/conversations/{conversation_id}")
    elif tasks and tasks[0].get("status") == "ERROR":
        print(f"Start task failed: {tasks[0].get('error', 'Unknown error')}")
        exit(1)
    else:
        status = tasks[0].get("status") if tasks else "no response"
        print(f"Start task status: {status}")
        time.sleep(5)
        attempts += 1

if not conversation_id:
    print("Timeout waiting for conversation to start")
    exit(1)

# Poll conversation until agent finishes (with timeout)
# Terminal states: finished, error, stuck, waiting_for_confirmation
max_attempts = 120  # 1 hour with 30-second intervals
attempts = 0
while attempts < max_attempts:
    conv_response = requests.get(
        f"{base_url}/api/v1/app-conversations",
        headers=headers,
        params={"ids": conversation_id}
    )
    conv_response.raise_for_status()
    conversations = conv_response.json()
    
    if not conversations:
        print("Warning: Conversation not found")
        time.sleep(30)
        attempts += 1
        continue
    
    conv = conversations[0]
    sandbox_status = conv.get("sandbox_status")
    exec_status = conv.get("execution_status")
    
    # Check sandbox health first
    if sandbox_status in ["ERROR", "MISSING"]:
        print(f"Sandbox failed with status: {sandbox_status}")
        exit(1)
    
    print(f"Execution status: {exec_status}")
    
    # Check for terminal states
    if exec_status in ["finished", "error", "stuck"]:
        print(f"Conversation completed with status: {exec_status}")
        break
    elif exec_status == "waiting_for_confirmation":
        print("Agent is waiting for user confirmation in the UI")
        print(f"Visit: {base_url}/conversations/{conversation_id}")
        break
    
    time.sleep(30)
    attempts += 1
else:
    print("Timeout waiting for conversation to complete")
    exit(1)
```

### Listing All Conversations

To list all your conversations, use the search endpoint:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://app.all-hands.dev/api/v1/app-conversations/search?limit=20" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Python (with requests)">
    ```python theme={null}
    import requests

    api_key = "YOUR_API_KEY"
    headers = {"Authorization": f"Bearer {api_key}"}

    response = requests.get(
        "https://app.all-hands.dev/api/v1/app-conversations/search",
        headers=headers,
        params={"limit": 20}
    )
    response.raise_for_status()
    result = response.json()

    for conv in result.get("items", []):
        print(f"ID: {conv['id']}, Status: {conv.get('execution_status')}")
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "items": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "sandbox_status": "RUNNING",
      "execution_status": "finished",
      "selected_repository": "yourusername/your-repo",
      "title": "Fix README"
    }
  ],
  "next_page_id": null
}
```

<Note>
  The search endpoint returns conversations in the `items` array. Use `next_page_id`
  for pagination if you have more conversations than the `limit`.
</Note>

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

***

## Migrating from V0 to V1 API

<Warning>
  The V0 API (`/api/conversations`) is deprecated and scheduled for removal on **April 1, 2026**.
  Please migrate to the V1 API (`/api/v1/app-conversations`) as soon as possible.
</Warning>

### Key Differences

| Feature          | V0 API                      | V1 API                                                      |
| ---------------- | --------------------------- | ----------------------------------------------------------- |
| Endpoint         | `POST /api/conversations`   | `POST /api/v1/app-conversations`                            |
| Message format   | `initial_user_msg` (string) | `initial_message.content` (array of content objects)        |
| Repository field | `repository`                | `selected_repository`                                       |
| Response         | Immediate `conversation_id` | Start task with `status` and eventual `app_conversation_id` |

### Migration Steps

1. **Update the endpoint URL**: Change from `/api/conversations` to `/api/v1/app-conversations`

2. **Update the request body**:
   * Change `repository` to `selected_repository`
   * Change `initial_user_msg` (string) to `initial_message` (object with content array):
   ```json theme={null}
   // V0 format
   { "initial_user_msg": "Your message here" }

   // V1 format
   { "initial_message": { "content": [{"type": "text", "text": "Your message here"}] } }
   ```

3. **Update response handling**: The V1 API returns a start task object. The conversation ID is in the `app_conversation_id` field (available when status is `READY`), or use the `id` field for the start task ID.

***

## Legacy API (V0) - Deprecated

<Warning>
  The V0 API is deprecated since version 1.0.0 and will be removed on **April 1, 2026**.
  New integrations should use the V1 API documented above.
</Warning>

### Starting a New Conversation (V0)

<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.conversation_id}`);
        console.log(`Status: ${conversation.status}`);

        return conversation;
      } catch (error) {
        console.error("Error starting conversation:", error);
      }
    }

    startConversation();
    ```
  </Tab>
</Tabs>

#### Response (V0)

```json theme={null}
{
  "status": "ok",
  "conversation_id": "abc1234"
}
```