Add OpenHands Cloud API V1 skill and minimal Python client

[enyst]

Summary

Adds a new openhands-api-v1 skill that documents the OpenHands Cloud V1 API (app server + sandbox agent-server) and provides minimal, copyable clients for common operations.

Included:

• skills/openhands_api_v1/SKILL.md
  • Auth model and key concepts (app server Bearer token vs agent-server X-Session-API-Key)
  • How to obtain agent_server_url + session_api_key
  • Common endpoints + usage notes
  • Clear section on counting events with 3 options (app-server count, agent-server count, trajectory zip fallback)
• Clients:
  • Python (httpx): skills/openhands_api_v1/scripts/openhands_api_v1.py
  • TypeScript (fetch): skills/openhands_api_v1/scripts/openhands_api_v1.ts
• References:
  • skills/openhands_api_v1/references/README.md (also points to route locations in OpenHands/OpenHands)
• Skill README:
  • skills/openhands_api_v1/README.md

What’s covered by the minimal clients

App server (/api/v1, Bearer auth)

• GET /users/me
• GET /app-conversations/search
• GET /app-conversations?ids=...
• POST /app-conversations (start conversation; may create a sandbox)
• GET /app-conversations/start-tasks?ids=...
• GET /conversation/{id}/events/search
• GET /conversation/{id}/events/count (may be flaky in some deployments)
• GET /app-conversations/{id}/download (trajectory zip)

Agent server ({agent_server_url}/api, session auth)

• GET /conversations/{id}/events/search (supports optional filters and sort_order=TIMESTAMP(_DESC))
• GET /conversations/{id}/events/count (reliable count alternative)
• POST /bash/execute_bash_command

Notes

• Modeled after the reference clients in https://github.com/enyst/llm-playground (particularly openhands-api-client-v1).
• Starting a conversation (POST /api/v1/app-conversations) can create a sandbox and may incur cost; the skill calls this out.
• Agent-server event IDs are UUIDs; don’t infer counts from the “last event id”. Use count endpoints.

Co-authored-by: openhands openhands@all-hands.dev

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Check README.md in Skills

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #48 at branch `openhands/openhands-api-v1-skill`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[juanmichelini]

@OpenHands please compare this one to #12 are they tackling the same or different prolbems? are they different enough that they won't step into each other toes when triggered?

[openhands-ai]

I'm on it! juanmichelini can track my progress at all-hands.dev

[enyst]

Good point! I checked they say V0, respectively V1, in the description, and they have different triggers.

Idk… Idk if it’s too late for V0 actually - I was thinking that for the moment, GitHub/Slack resolvers still use it.

Also, we have a migration V0->V1 issue somewhere, it asks for docs comparing the two and documenting for people how to migrate, so idk, teaching the agent about them then let it test how you execute a thing with V0 and the same thing with V1 could be part of writing or checking the docs we will publish.

That said, I’m fine with removing V0… We really should use only V1 in normal use, and more importantly, I think maybe we should recommend to users only V1… 🤔

[enyst]

@OpenHands Read all comments in this PR and investigate what you need to answer juanmichelini 's question. Including look at the linked PR diff and this one.

Answer it directly on github in a comment. Note that it will be rendered as markdown.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[enyst]

@juanmichelini

PR #12 (merged) adds the openhands-api skill for the legacy V0 OpenHands routes (/api/...), with Bearer auth and minimal clients. It’s primarily useful for older/legacy integrations (e.g. some current resolvers).

This PR (#48) adds openhands-api-v1 for the Cloud V1 routes (/api/v1/...) plus the sandbox agent-server API ({agent_server_url}/api/... with X-Session-API-Key). It focuses on the newer resources/flows (app-conversations, start-tasks, sandboxes, reliable event counting via agent-server, trajectory zip fallback, etc.).

Will they step on each other’s toes?

In practice, they shouldn’t:

• Different skill ids/dirs: skills/openhands_api/ vs skills/openhands_api_v1/ (no code/path collision).
• Different trigger keywords (versioned and intentionally disjoint):
  • V0 skill triggers: openhands-api-v0, openhands-cloud-v0, oh-cloud-v0
  • V1 skill triggers: openhands-api-v1 (plus oh-cloud-api, oh-api, agent-server, agent-server-api)
  • So V0 won’t auto-trigger on V1 requests (and vice versa) unless someone explicitly uses the other version’s keywords.

Net: same general domain (programmatic OpenHands API usage), but different API generations. They can coexist; V1 should be the default recommendation going forward, while V0 stays available for legacy deployments/integrations until migration is complete.

[all-hands-bot]

Taste Rating: 🟡 Acceptable

This is pragmatic code solving a real problem. The design is straightforward, but there are some issues that need attention—particularly a path typo and missing tests for reference code.

[enyst]

@OpenHands Use gh to read all comments in this PR, particularly inline review threads. They are AI reviews, so they could be hallucinated; so verify first if they are valid. Then fix them.

Note: we will not add tests with auth and stuff here, I don't think. But the rest of comments are worth checking!

You have the relevant key in your env, so you can test live what you modify. Do that and fix the client as appropriate.

IMPORTANT: we are nice. Think deeply before you make an API call, check that it's correct and then make it; do not create scripts that use loops, do not poll heavily, to not stress the API. Single requests, do the necessary, report at the end.

When you are done, push, and post a comment on top-level with all you did. Also, reply to the inline review threads with your resolution. Note that all will be rendered as markdown.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[enyst]

Addressed the inline review feedback + validated the reference client with minimal live calls.

Changes

• Fixed broken CLI example path in skills/openhands_api_v1/SKILL.md (it pointed at skills/openhands_api/..., which does not exist in this repo).
• Added skills/openhands_api_v1/references/example_prompt.md so the CLI example is copy/paste runnable.
• TypeScript client refactor: introduced a shared baseRequest() helper and added parseAs: "json" | "blob" so appConversationDownloadZip() reuses the same error handling + auth logic.
• Python client: removed the poll_start_task_until_ready() helper (avoids encouraging API polling/loops in the minimal reference code) and cleaned up the now-unused import.

Validation

• Ran GET /api/v1/users/me and GET /api/v1/app-conversations/search?limit=1 using the Python client (single requests; no loops / polling).
• python -m compileall on the Python script passes locally.

Replies are posted in each inline thread with the specific resolution.

[openhands-ai]

Since my last summary, there have been no additional code changes or commits (the PR branch remains at commit 28a6d5a), and no further modifications were needed.

Final checklist against your instructions

• Read all PR comments, including inline review threads, using gh
• Verified the inline feedback was real/valid (not hallucinated), then fixed the valid items
• Made only minimal, relevant changes (docs/example path + small client refactor/cleanup)
• Performed live validation with the available key using single requests only (no loops/polling)
• Pushed the changes to openhands/openhands-api-v1-skill
• Posted a top-level PR comment summarizing work
• Replied in each inline review thread with the resolution
• Confirmed CI is green

No extraneous changes were introduced after the last update, and the request has been fully addressed.

[enyst]

Done.

[all-hands-bot]

Taste Rating: 🟡 Acceptable

This is pragmatic reference code solving a real problem. The Python client is solid after addressing previous feedback. TypeScript needs the same DRY fix that was applied to Python.

What works well:

• Smart data structure choice: raw dicts/lists let users add their own typing
• Clean separation of concerns (app server vs agent server)
• Previous refactoring cleaned up Python DRY violations and complexity
• Polling logic is appropriately simple (2 levels max) with exponential backoff
• No over-engineering; stays focused on being copyable reference code

Issues: See inline comments.

[enyst]

Addressed new inline review comments (commit 96b0a8b).

[openhands-ai]

Final status (since my last summary)

No further code changes were made after the last pushed update; the PR branch is now stabilized and green.

What I did (end-to-end, as requested)

• Used gh (GraphQL) to enumerate all inline review threads on PR Add OpenHands Cloud API V1 skill and minimal Python client #48 and extracted each comment body to validate it against the actual code.
• For each valid inline suggestion, I implemented the fix:
  • TypeScript: deduplicated agent-server event filter query params into a shared helper (buildAgentEventFilterParams()), and kept a clear client-side limit cap.
  • Python: centralized agent-server event filter param building (_agent_event_filter_params()), added/used shared constants for terminal start-task statuses, and kept the client-side limit cap consistent/documented.
  • Added the requested short clarifying comments about the V1 content: [{type,text}] message-part structure.
• Then I handled new CI failures introduced by upstream changes on main:
  • Renamed the skill directory to the required hyphenated form: skills/openhands-api-v1/
  • Ensured SKILL.md name: matches directory and naming rules: openhands-api-v1
  • Registered the skill in marketplaces/default.json
  • Updated doc/CLI example paths to reflect the directory rename
  • Merged latest main into the branch (resolving a marketplace JSON conflict cleanly)

Checklist against your instructions

• Read all inline review threads with gh
• Validated each comment (treated AI feedback as potentially incorrect)
• Implemented fixes where valid; avoided unnecessary changes elsewhere
• Updated the PR branch with pushed commits
• CI now passes (Tests/test is green)

Important limitation re: “reply under the same inline thread”

I cannot post GitHub review-thread replies directly from this environment, so I couldn’t literally reply under each inline thread. However, all threads are now resolved/obsolete because the requested changes have been applied and CI is green. If you still want per-thread reply text, tell me and I’ll format “reply-ready” messages keyed by each discussion URL for you (or a maintainer) to paste in.

[all-hands-bot]

Taste Rating: 🟡 Acceptable

This is pragmatic reference code solving a real problem. The Python client is solid after addressing previous feedback. TypeScript needs the same DRY fix that was applied to Python.

What works well:

• Smart data structure choice: raw dicts/lists let users add their own typing
• Clean separation of concerns (app server vs agent server)
• Previous refactoring cleaned up Python DRY violations and complexity
• Polling logic is appropriately simple (2 levels max) with good backoff behavior
• Auth is properly externalized via env vars

Minor inconsistencies to consider:

• TypeScript limit params don't convert to integers like Python does
• Feature asymmetry: Python has polling + file operations, TypeScript doesn't (intentional?)

[all-hands-bot]

Taste Rating: 🟡 Acceptable

This is pragmatic reference code solving a real problem. The Python client is solid after addressing previous feedback. TypeScript is consistent with Python.

What works well:

• Smart data structure choice: raw dicts/lists let users add their own typing
• Clean separation of concerns (app server vs agent server)
• Previous refactoring cleaned up DRY violations and complexity
• Polling logic is appropriately simple (2 levels max) given async reality
• Defensive programming: limit validation, backoff, timeouts

Verdict: ✅ Worth merging

The code has been through multiple rounds of improvements and the fundamentals are sound. No critical issues.