Openhands API

This skill documents the OpenHands Cloud API (V1), commonly used agent-server APIs, and small, easy-to-copy clients. Windows PowerShell equivalents for the shell examples in this skill are in references/windows.md.

It is intentionally focused on common OpenHands API workflows:

• Defaults to OpenHands Cloud (https://app.all-hands.dev).
• Targets the V1 app server REST API under /api/v1/....
• Includes a few agent server endpoints (inside a sandbox) that use X-Session-API-Key.
• Covers the multi-conversation delegation pattern: start separate Cloud conversations when you want fresh context windows or background work.
• Covers local Agent Canvas backend conversations: start or inspect conversations by calling a local agent server directly.

When to use this skill

Use this skill when you need to:

• start or inspect OpenHands Cloud conversations from code
• monitor async startup via start-task polling
• monitor execution status for long-running jobs
• create separate Cloud conversations for parallel or background work
• access sandbox agent-server endpoints once a conversation is running
• start or inspect conversations on a local Agent Canvas backend or local agent server

Auth

App server (Cloud)

Use Bearer auth:

• Header: Authorization: Bearer <OPENHANDS_CLOUD_API_KEY>
• Preferred env var: OPENHANDS_CLOUD_API_KEY
• Backward-compatible env var: OPENHANDS_API_KEY

Agent server (inside a sandbox)

Use session auth:

• Header: X-Session-API-Key: <session_api_key>

How to obtain agent_server_url and session_api_key:

1. Start or fetch an app conversation via the app server (Bearer auth), e.g.:
   • POST /api/v1/app-conversations
   • or GET /api/v1/app-conversations?ids=<conversation_id>
2. In the returned JSON, look for sandbox/runtime connection fields (names vary slightly by deployment/version). Common patterns:
   • a sandbox object containing agent_server_url (or similar)
   • a session key such as session_api_key (or similar)
3. Use those values to call the agent server directly:
   • Base: {agent_server_url}/api/...
   • Header: X-Session-API-Key: <session_api_key>

Example (common field names; adjust to your deployment):

# using the minimal Python client (`OpenHandsAPI`)
conv = api.app_conversation_get(app_conversation_id)

session_api_key = conv.get("session_api_key")
conversation_url = conv.get("conversation_url", "")

# `conversation_url` often looks like: https://<runtime-host>/api/conversations/<id>
agent_server_url = conversation_url.rsplit("/api/conversations", 1)[0]

If those fields are not present on the conversation record, list/search sandboxes (GET /api/v1/sandboxes/search) and use the sandbox referenced by the conversation to locate the agent server URL + session key.

Local Agent Canvas backend

Use the local backend flow only for local Agent Canvas / agent-server development, such as agent-canvas, agent-canvas --backend-only, or npm run dev with ingress at http://localhost:8000. This calls the agent server directly with X-Session-API-Key. It is not an automation, and it is different from OpenHands Cloud delegation through POST /api/v1/app-conversations, which uses Bearer auth against the Cloud app API and may return asynchronous start-task records.

When Agent Canvas runs locally, the launcher uses LOCAL_BACKEND_API_KEY when it is set. Otherwise it generates and persists the session API key at ~/.openhands/agent-canvas/api-key.txt. Set OH_SESSION_API_KEY_PATH to override the persisted key path. Never print, log, or paste the actual key; use command substitution or an environment variable in examples and scripts.

LOCAL_AGENT_SERVER_URL="${LOCAL_AGENT_SERVER_URL:-http://localhost:8000}"
SESSION_API_KEY="${LOCAL_BACKEND_API_KEY:-$(cat "${OH_SESSION_API_KEY_PATH:-$HOME/.openhands/agent-canvas/api-key.txt}")}"

Check the local server before creating a backend conversation:

curl -sS "${LOCAL_AGENT_SERVER_URL}/server_info" \
  -H "X-Session-API-Key: ${SESSION_API_KEY}"

Start a backend conversation with POST /api/conversations. Include the agent settings and workspace expected by that backend. Local agent-server calls use an explicit workspace such as {"kind": "LocalWorkspace", "working_dir": "/workspace"}; Cloud app-conversation delegation instead uses app-server fields such as selected_repository and selected_branch. If you are starting the conversation from an existing Agent Canvas session, pass through the current configured settings or encrypted settings rather than hard-coding secrets into scripts.

CONVERSATION_JSON=$(curl -sS -X POST "${LOCAL_AGENT_SERVER_URL}/api/conversations" \
  -H "X-Session-API-Key: ${SESSION_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "agent": {
    "kind": "Agent",
    "llm": {
      "model": "your-model-provider/your-model-name",
      "api_key": "**********"
    },
    "tools": [
      {"name": "terminal"},
      {"name": "file_editor"},
      {"name": "task_tracker"}
    ]
  },
  "workspace": {"kind": "LocalWorkspace", "working_dir": "/workspace"},
  "initial_message": {
    "content": [{"text": "Summarize the current workspace."}],
    "run": true
  }
}
JSON
)
CONVERSATION_ID=$(python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])' <<<"${CONVERSATION_JSON}")
printf 'Conversation: %s/api/conversations/%s\n' "${LOCAL_AGENT_SERVER_URL}" "${CONVERSATION_ID}"

Poll status and inspect recent events:

curl -sS "${LOCAL_AGENT_SERVER_URL}/api/conversations/${CONVERSATION_ID}" \
  -H "X-Session-API-Key: ${SESSION_API_KEY}"

curl -sS "${LOCAL_AGENT_SERVER_URL}/api/conversations/${CONVERSATION_ID}/events/search?limit=20&sort_order=TIMESTAMP_DESC" \
  -H "X-Session-API-Key: ${SESSION_API_KEY}"

If the same base URL serves the Agent Canvas UI, the browser route is:

printf '%s/conversations/%s\n' "${LOCAL_AGENT_SERVER_URL}" "${CONVERSATION_ID}"

Common V1 app server endpoints

The following are the main endpoints implemented in the minimal client:

• GET /api/v1/users/me — validate auth and inspect current account
• GET /api/v1/app-conversations/search?limit=... — list recent conversations
• GET /api/v1/app-conversations?ids=... — fetch conversation records by id (batch)
• GET /api/v1/app-conversations/count — count conversations
• POST /api/v1/app-conversations — start a new conversation (creates a sandbox)
• GET /api/v1/app-conversations/start-tasks?ids=... — check async start-task status
• GET /api/v1/conversation/{app_conversation_id}/events/search?limit=... — read conversation events
• GET /api/v1/conversation/{app_conversation_id}/events/count — count events
• GET /api/v1/sandboxes/search?limit=... — list sandboxes
• POST /api/v1/sandboxes/{sandbox_id}/pause / .../resume — manage sandbox lifecycle
• GET /api/v1/app-conversations/{app_conversation_id}/download — download trajectory zip

Delegating work with additional Cloud conversations

Use the Cloud API when you want a separate OpenHands conversation with its own fresh context window. This is useful for:

• background jobs that can run independently
• parallel investigations or implementation tasks
• long-running work where you want to keep the current conversation focused
• task-specific contexts, such as one conversation building a component while another runs tests

Delegation checklist

When you start a delegated Cloud conversation:

1. Write a self-contained task description. Do not assume the new conversation has any context from the current one.
2. Include the repository, branch, relevant file paths, constraints, and expected output.
3. Start the new conversation with POST /api/v1/app-conversations.
4. Poll the start-task until status is READY and you have an app_conversation_id.
5. Monitor the delegated conversation via GET /api/v1/app-conversations?ids=....
6. Share or store the conversation's conversation_ui_url from that response. It opens the conversation in Agent Canvas. If the server does not return it, use <base_url>/canvas/conversations/<app_conversation_id>, where <base_url> is the server you called the API on. Never share conversation_url; it is the sandbox's agent-server API, not a page users can open.