# OpenHands

> Hand coding work to OpenHands, the open-source AI software engineer. Describe a task in plain words and pick a repository: the agent clones it, runs commands and edits files in a sandbox of its own, then replies with what it did. Send follow-up instructions, read the files it wrote, and collect the diff of its changes for review.

App · AI Agents · 18 actions. Web page: https://docs.lodol.com/docs/integrations/openhands

## Actions

### Check credit balance

How many OpenHands Cloud credits your account has left, in US dollars. Tasks on the free models don't use any; the others are paid for from this balance.

**Inputs**: None.

**Outputs**

- `credits` (number)

**Example output**

```json
{
  "credits": 10.0
}
```

### Check on a task

See where a task has got to: starting, running, finished, stopped with an error, or waiting on you. Once it has finished, this includes the agent's answer.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.

**Outputs**

- `answer` (text)
- `branch` (text)
- `conversation_id` (text)
- `created_at` (text)
- `done` (true/false)
- `error` (text)
- `link` (text)
- `model` (text)
- `repository` (text)
- `sandbox_status` (text)
- `shared` (true/false)
- `startup_stage` (text)
- `status` (text)
- `title` (text)
- `updated_at` (text)

**Example output**

```json
{
  "answer": "Fixed the empty-email check in signup.py and added a test for it.",
  "branch": "main",
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "created_at": "2026-09-22T18:45:16.612776Z",
  "done": true,
  "error": "",
  "link": "https://app.all-hands.dev/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "model": "openhands/deepseek-v4.1-flash",
  "repository": "octocat/hello-world",
  "sandbox_status": "running",
  "shared": false,
  "startup_stage": "",
  "status": "finished",
  "title": "Fix empty email on signup",
  "updated_at": "2026-09-22T18:49:04.813393Z"
}
```

### Delete a task

Delete a task from your OpenHands account and shut down its sandbox, along with any files in it. OpenHands still keeps the task's message history on its side.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.

**Outputs**

- `conversation_id` (text)
- `deleted` (true/false)

**Example output**

```json
{
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "deleted": true
}
```

### Get a task's code changes

The files the agent added, changed or deleted, each with a diff, ready to post for review. Uncommitted changes are included. A paused task is woken first.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.
- Include the diffs (`include_diffs`, true/false): Turn off to list just which files changed, which is quicker for a large change. Default: `true`.

**Outputs**

- `changes` (list)
- `conversation_id` (text)
- `count` (number)
- `diff` (text)
- `repository` (text)

**Example output**

```json
{
  "changes": [
    {
      "diff": "--- a/signup.py\n+++ b/signup.py\n@@ -1 +1 @@\n-if email is None:\n+if not email:\n",
      "path": "signup.py",
      "status": "updated"
    }
  ],
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "count": 1,
  "diff": "--- a/signup.py\n+++ b/signup.py\n@@ -1 +1 @@\n-if email is None:\n+if not email:\n",
  "repository": "octocat/hello-world"
}
```

### Get a task's messages

The conversation between you and the agent, oldest first: every instruction it was given and every reply.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.
- How many (`limit`, number): The most recent messages to return, up to 200. From 1 to 200. Default: `50`.

**Outputs**

- `conversation_id` (text)
- `count` (number)
- `latest_answer` (text)
- `messages` (list)

**Example output**

```json
{
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "count": 2,
  "latest_answer": "Fixed the empty-email check in signup.py and added a test for it.",
  "messages": [
    {
      "role": "user",
      "sent_at": "2026-09-22T18:48:31.073476",
      "text": "The signup form accepts an empty email. Fix it."
    },
    {
      "role": "agent",
      "sent_at": "2026-09-22T18:49:04.297736",
      "text": "Fixed the empty-email check in signup.py and added a test for it."
    }
  ]
}
```

### List a task's files

The files in a task's workspace, relative to its repository. A paused task is woken first, which usually takes under a minute.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.
- Matching (`matching`, text): Only files matching this: a pattern with * such as *.md, or words in the path such as src/. Leave blank for every file.

**Outputs**

- `conversation_id` (text)
- `count` (number)
- `files` (list)
- `total` (number)

**Example output**

```json
{
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "count": 3,
  "files": [
    "README.md",
    "signup.py",
    "tests/test_signup.py"
  ],
  "total": 3
}
```

### List branches

The branches of a repository OpenHands can work on.

**Inputs**

- Repository (`repository`, text, required): The repository, as owner/repository.
- Search (`search`, text): Only branches whose name contains these words.
- How many (`limit`, number): The most to return. From 1 to 100. Default: `50`.

**Outputs**

- `branches` (list)
- `count` (number)
- `has_more` (true/false)
- `repository` (text)

**Example output**

```json
{
  "branches": [
    {
      "commit_sha": "3f786850e387550fdab836ed7e6dc881de23001b",
      "last_pushed_at": "2026-09-22T17:35:18Z",
      "name": "main"
    }
  ],
  "count": 1,
  "has_more": false,
  "repository": "octocat/hello-world"
}
```

### List repositories

The repositories OpenHands can work on, from the GitHub, GitLab or Bitbucket account connected to OpenHands.

**Inputs**

- Search (`search`, text): Only repositories whose name contains these words.
- How many (`limit`, number): The most to return. From 1 to 100. Default: `30`.

**Outputs**

- `count` (number)
- `has_more` (true/false)
- `provider` (text)
- `repositories` (list)

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "provider": "github",
  "repositories": [
    {
      "default_branch": "main",
      "full_name": "octocat/hello-world",
      "is_public": true,
      "owner_type": "user",
      "provider": "github"
    }
  ]
}
```

### List tasks

See the tasks on your OpenHands account, newest first. A task whose sandbox OpenHands has paused shows as paused here; 'Check on a task' says whether it had finished.

**Inputs**

- Title contains (`title_contains`, text): Only tasks whose title contains this text, with the same capital letters.
- Started after (`created_after`, date and time): Only tasks started on or after this moment.
- How many (`limit`, number): The most to return. From 1 to 100. Default: `20`.

**Outputs**

- `count` (number)
- `has_more` (true/false)
- `tasks` (list)

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "tasks": [
    {
      "branch": "main",
      "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
      "created_at": "2026-09-22T18:45:16.612776Z",
      "link": "https://app.all-hands.dev/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
      "model": "openhands/deepseek-v4.1-flash",
      "repository": "octocat/hello-world",
      "sandbox_status": "running",
      "shared": false,
      "status": "finished",
      "title": "Fix empty email on signup",
      "updated_at": "2026-09-22T18:49:04.813393Z"
    }
  ]
}
```

### List what a task did

The steps the agent took, oldest first: each command it ran with its output and exit code, each file it looked at or edited, and any errors. Useful as an audit trail.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.
- Show (`show`, text): Which steps to include. One of: `everything` (Everything the agent did), `commands` (Terminal commands only), `errors` (Errors only). Default: `everything`.
- How many (`limit`, number): The most recent steps to return, up to 200. From 1 to 200. Default: `50`.

**Outputs**

- `conversation_id` (text)
- `count` (number)
- `steps` (list)

**Example output**

```json
{
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "count": 1,
  "steps": [
    {
      "at": "2026-09-22T18:48:43.834925",
      "command": "pytest tests/test_signup.py",
      "exit_code": 0,
      "failed": false,
      "output": "4 passed in 0.12s",
      "path": "",
      "summary": "Run the signup tests",
      "tool": "terminal"
    }
  ]
}
```

### Pause a task

Stop the agent where it is by pausing the task's sandbox. That also makes room for another task, since OpenHands limits how many run at once. Nothing is lost: send it a follow-up message to carry on.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.

**Outputs**

- `conversation_id` (text)
- `link` (text)
- `paused` (true/false)

**Example output**

```json
{
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "link": "https://app.all-hands.dev/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "paused": true
}
```

### Read a file from a task

The contents of a file in a task's workspace, such as a report the agent wrote. When there is no such file, 'found' comes back false rather than the step handing on an empty file. A paused task is woken first.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.
- File (`path`, text, required): The file's path relative to the repository, as 'List a task's files' shows it.

**Outputs**

- `content` (text)
- `conversation_id` (text)
- `found` (true/false)
- `path` (text)
- `size` (number)
- `truncated` (true/false)

**Example output**

```json
{
  "content": "# Report\n\nAll four signup tests pass.\n",
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "found": true,
  "path": "docs/report.md",
  "size": 38,
  "truncated": false
}
```

### Rename a task

Give a task a new title in OpenHands.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.
- New title (`title`, text, required): What to call the task.

**Outputs**

- `conversation_id` (text)
- `link` (text)
- `title` (text)

**Example output**

```json
{
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "link": "https://app.all-hands.dev/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "title": "Fix empty email on signup"
}
```

### Resume a task

Wake a paused task's sandbox (usually within a minute, occasionally two) and report where the agent had got to. The agent doesn't pick up its work by itself; send it a follow-up message for that.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.

**Outputs**

- `answer` (text)
- `branch` (text)
- `conversation_id` (text)
- `created_at` (text)
- `done` (true/false)
- `error` (text)
- `link` (text)
- `model` (text)
- `repository` (text)
- `sandbox_status` (text)
- `shared` (true/false)
- `startup_stage` (text)
- `status` (text)
- `title` (text)
- `updated_at` (text)

**Example output**

```json
{
  "answer": "Fixed the empty-email check in signup.py and added a test for it.",
  "branch": "main",
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "created_at": "2026-09-22T18:45:16.612776Z",
  "done": true,
  "error": "",
  "link": "https://app.all-hands.dev/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "model": "openhands/deepseek-v4.1-flash",
  "repository": "octocat/hello-world",
  "sandbox_status": "running",
  "shared": false,
  "startup_stage": "",
  "status": "finished",
  "title": "Fix empty email on signup",
  "updated_at": "2026-09-22T18:49:04.813393Z"
}
```

### Send a follow-up message

Give a task more instructions, and wait for the agent's reply. The agent keeps everything from earlier in the task, files included. A paused task is woken first, so this is also how to set a paused or stuck task going again.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.
- Message (`message`, text, required): What to tell the agent.
- Wait up to (minutes) (`wait_minutes`, number): How long this step waits for the agent to finish. If it is still working when the wait runs out, the step succeeds with 'done' set to false, and 'Wait for a task to finish' can pick it up later. Set 0 to carry on straight away. From 0 to 30. Default: `10`.

**Outputs**

- `answer` (text)
- `branch` (text)
- `conversation_id` (text)
- `created_at` (text)
- `done` (true/false)
- `error` (text)
- `link` (text)
- `model` (text)
- `repository` (text)
- `sandbox_status` (text)
- `shared` (true/false)
- `startup_stage` (text)
- `status` (text)
- `title` (text)
- `updated_at` (text)

**Example output**

```json
{
  "answer": "Fixed the empty-email check in signup.py and added a test for it.",
  "branch": "main",
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "created_at": "2026-09-22T18:45:16.612776Z",
  "done": true,
  "error": "",
  "link": "https://app.all-hands.dev/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "model": "openhands/deepseek-v4.1-flash",
  "repository": "octocat/hello-world",
  "sandbox_status": "running",
  "shared": false,
  "startup_stage": "",
  "status": "finished",
  "title": "Fix empty email on signup",
  "updated_at": "2026-09-22T18:49:04.813393Z"
}
```

### Share a task

Turn a task's public link on or off. Anyone with the link can read the whole task without signing in, including your instructions, every command the agent ran, and the contents of files it read.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.
- Shared (`shared`, true/false): On to make the link work, off to stop it working. Default: `true`.

**Outputs**

- `conversation_id` (text)
- `link` (text)
- `share_link` (text)
- `shared` (true/false)

**Example output**

```json
{
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "link": "https://app.all-hands.dev/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "share_link": "https://app.all-hands.dev/shared/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "shared": true
}
```

### Start a task

Give OpenHands a coding task in plain words. The agent clones the repository into a sandbox of its own, runs commands and edits files there, and replies when it is done. This step waits for that reply (starting alone takes about a minute), and hands back the task's ID for the steps after it.

**Inputs**

- Task (`task`, text, required): What the agent should do, as you'd tell a person.
- Repository (`repository`, text): The repository to work on, as owner/repository. Leave blank for a task that needs no existing code.
- Branch (`branch`, text): The branch to start from. Leave blank for the repository's default branch.
- Title (`title`, text): A name for the task in OpenHands. Leave blank and OpenHands writes one.
- Model (`model`, text): The AI model the agent uses. Leave blank for the one in your OpenHands settings. The free ones cost no credits; the others need credits on your account.
- Plan only (`plan_only`, true/false): Have the agent study the code and write a plan instead of making the change. The plan is saved as .agents_tmp/PLAN.md, and summarized in its answer. Default: `false`.
- Wait up to (minutes) (`wait_minutes`, number): How long this step waits for the agent to finish. If it is still working when the wait runs out, the step succeeds with 'done' set to false, and 'Wait for a task to finish' can pick it up later. Set 0 to carry on straight away. From 0 to 30. Default: `10`.

**Outputs**

- `answer` (text)
- `branch` (text)
- `conversation_id` (text)
- `created_at` (text)
- `done` (true/false)
- `error` (text)
- `link` (text)
- `model` (text)
- `repository` (text)
- `sandbox_status` (text)
- `shared` (true/false)
- `startup_stage` (text)
- `status` (text)
- `title` (text)
- `updated_at` (text)

**Example output**

```json
{
  "answer": "Fixed the empty-email check in signup.py and added a test for it.",
  "branch": "main",
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "created_at": "2026-09-22T18:45:16.612776Z",
  "done": true,
  "error": "",
  "link": "https://app.all-hands.dev/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "model": "openhands/deepseek-v4.1-flash",
  "repository": "octocat/hello-world",
  "sandbox_status": "running",
  "shared": false,
  "startup_stage": "",
  "status": "finished",
  "title": "Fix empty email on signup",
  "updated_at": "2026-09-22T18:49:04.813393Z"
}
```

### Wait for a task to finish

Hold the workflow until a task finishes, then hand on the agent's answer. Use it after a 'Start a task' or 'Send a follow-up message' step that didn't wait, for example to start several tasks at once and collect their answers afterwards.

**Inputs**

- Task (`conversation_id`, text, required): The task's ID, from 'Start a task' or 'List tasks'. Its OpenHands link works too.
- Wait up to (minutes) (`wait_minutes`, number): How long this step waits for the agent to finish. If it is still working when the wait runs out, the step succeeds with 'done' set to false, and 'Wait for a task to finish' can pick it up later. Set 0 to carry on straight away. From 0 to 30. Default: `10`.

**Outputs**

- `answer` (text)
- `branch` (text)
- `conversation_id` (text)
- `created_at` (text)
- `done` (true/false)
- `error` (text)
- `link` (text)
- `model` (text)
- `repository` (text)
- `sandbox_status` (text)
- `shared` (true/false)
- `startup_stage` (text)
- `status` (text)
- `title` (text)
- `updated_at` (text)

**Example output**

```json
{
  "answer": "Fixed the empty-email check in signup.py and added a test for it.",
  "branch": "main",
  "conversation_id": "5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "created_at": "2026-09-22T18:45:16.612776Z",
  "done": true,
  "error": "",
  "link": "https://app.all-hands.dev/conversations/5f3a9c2e7b1d4e8fa0c6b2d9e4f1a7c3",
  "model": "openhands/deepseek-v4.1-flash",
  "repository": "octocat/hello-world",
  "sandbox_status": "running",
  "shared": false,
  "startup_stage": "",
  "status": "finished",
  "title": "Fix empty email on signup",
  "updated_at": "2026-09-22T18:49:04.813393Z"
}
```