openhands-api

This skill provides a minimal, easy-to-copy OpenHands API client for starting and monitoring conversations.

It is intentionally small and focused:

• Defaults to OpenHands Cloud (https://app.all-hands.dev).
• Targets the legacy V0 REST API routes implemented in OpenHands/OpenHands under openhands/server/routes/.
• Implements only a few core endpoints so an AI agent can quickly adapt/extend it.

Quick start (Python)

from scripts.openhands_api import OpenHandsAPI

api = OpenHandsAPI(api_key="...")  # or set OPENHANDS_API_KEY

conv = api.create_conversation(
    initial_user_msg="Please audit this repo for flaky tests and open a PR fixing them.",
    repository="owner/repo",
    selected_branch="main",
)
conversation_id = conv["conversation_id"]

final = api.poll_until_terminal(conversation_id, timeout_s=1800, poll_interval_s=30)
print(final["status"], final.get("url"))

Quick start (TypeScript)

import { OpenHandsAPI } from "./scripts/openhands_api";

const api = new OpenHandsAPI({ apiKey: process.env.OPENHANDS_API_KEY! });

const conv = await api.createConversation({
  initialUserMsg: "Run dependency upgrades and open a PR.",
  repository: "owner/repo",
  selectedBranch: "main",
});

const final = await api.pollUntilTerminal(conv.conversation_id, {
  timeoutMs: 30 * 60_000,
  pollIntervalMs: 30_000,
});

console.log(final.status, final.url);

Example (modeled after enyst/playground#105)

The following example shows a simple automation pattern:

1. Start a conversation with a prompt template
2. Print the conversation URL for humans
3. Optionally poll until completion

export OPENHANDS_API_KEY="..."
python skills/openhands_api/scripts/openhands_api.py \
  new-conversation \
  --prompt-file skills/openhands_api/references/example_prompt.md \
  --repo owner/repo \
  --branch main \
  --poll

Notes for AI agents extending this client

• The server expects a Bearer token (Authorization: Bearer <OPENHANDS_API_KEY>).
• The most important endpoint is POST /api/conversations.
• If you need streaming/logs, the V0 server exposes GET /api/conversations/{conversation_id}/events.
• If you need the full event history in one call, use GET /api/conversations/{conversation_id}/trajectory.

See also:

• skills/openhands_api/references/README.md (API docs pointers)
• skills/openhands_api/scripts/openhands_api.py and skills/openhands_api/scripts/openhands_api.ts