π 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_.jsonnew file mode 100644index 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.mdnew file mode 100644index 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 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.mdxindex 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 StartedAfter visiting OpenHands Cloud, you will be asked to connect with your GitHub or GitLab account:diff --git a/docs/sidebars.ts b/docs/sidebars.tsindex 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.pngnew file mode 100644index 0000000000..713a4a79d4Binary files /dev/null and b/docs/static/img/docs/api-key-generation.png differ