For more detailed information about the API, refer to the OpenHands 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 account.
  2. Navigate to the Settings page.
  3. Select the API Keys tab.
  4. Click Create API Key.
  5. Give your key a descriptive name (Example: “Development” or “Production”) and select Create.
  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 to perform a task, you’ll need to make a POST request to the conversation endpoint.

​
Request Parameters

ParameterTypeRequiredDescription
initial_user_msgstringYesThe initial message to start the conversation.
repositorystringNoGit repository name to provide context in the format owner/repo. You must have access to the repo.

​
Examples

​
Response

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

{
  "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.

​
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

​
Response

The response is formatted as follows:

{
  "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

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.