Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Add OpenHands Cloud API documentation (#8127)

Graham Neubig722711db3b5b
diff --git a/docs/modules/usage/cloud/_category_.json b/docs/modules/usage/cloud/_category_.json
new file mode 100644
index 0000000000..91b8bb67d0
--- /dev/null
+++ b/docs/modules/usage/cloud/_category_.json
@@ -0,0 +1,8 @@
+{
+ "label": "OpenHands Cloud",
+ "position": 9,
+ "link": {
+ "type": "generated-index",
+ "description": "Documentation for OpenHands Cloud features and services."
+ }
+}
diff --git a/docs/modules/usage/cloud/cloud-api.md b/docs/modules/usage/cloud/cloud-api.md
new file mode 100644
index 0000000000..f9b483063c
--- /dev/null
+++ b/docs/modules/usage/cloud/cloud-api.md
@@ -0,0 +1,177 @@
+# 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](https://docs.all-hands.dev/swagger-ui/).
+
+## 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 page](https://app.all-hands.dev/settings)
+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 Key Generation](/img/docs/api-key-generation.png)
+
+## 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
+
+<details>
+<summary>cURL</summary>
+
+```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"
+ }'
+```
+</details>
+
+<details>
+<summary>Python (with requests)</summary>
+
+```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['id']}")
+print(f"Status: {conversation['status']}")
+```
+</details>
+
+<details>
+<summary>TypeScript/JavaScript (with fetch)</summary>
+
+```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();
+```
+
+</details>
+
+#### Response
+
+The API will return a JSON object with details about the created conversation:
+
+```json
+{
+ "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
+
+<details>
+<summary>cURL</summary>
+
+```bash
+curl -X GET "https://app.all-hands.dev/api/conversations/{conversation_id}" \
+ -H "Authorization: Bearer YOUR_API_KEY"
+```
+</details>
+
+#### Response
+
+The response is formatted as follows:
+
+```json
+{
+ "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
+
+The API has a limit of 10 simultaneous conversations per account. If you need a higher limit for your use case, please contact us at [[email protected]](mailto:[email protected]).
+
+If you exceed this limit, the API will return a 429 Too Many Requests response.
diff --git a/docs/modules/usage/cloud/openhands-cloud.mdx b/docs/modules/usage/cloud/openhands-cloud.mdx
index dba9e18528..9a95b25e9a 100644
--- a/docs/modules/usage/cloud/openhands-cloud.mdx
+++ b/docs/modules/usage/cloud/openhands-cloud.mdx
@@ -6,6 +6,8 @@ OpenHands Cloud is the cloud hosted version of OpenHands by All Hands AI.
OpenHands Cloud can be accessed at https://app.all-hands.dev/.
+You can also interact with OpenHands Cloud programmatically using the [API](./cloud-api).
+
## Getting Started
After visiting OpenHands Cloud, you will be asked to connect with your GitHub or GitLab account:
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index 2d346c8596..fc20a7044a 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -27,7 +27,11 @@ const sidebars: SidebarsConfig = {
label: 'Openhands Cloud',
id: 'usage/cloud/openhands-cloud',
},
-
+ {
+ type: 'doc',
+ label: 'Cloud API',
+ id: 'usage/cloud/cloud-api',
+ },
{
type: 'doc',
label: 'Cloud GitHub Resolver',
diff --git a/docs/static/img/docs/api-key-generation.png b/docs/static/img/docs/api-key-generation.png
new file mode 100644
index 0000000000..713a4a79d4
Binary files /dev/null and b/docs/static/img/docs/api-key-generation.png differ