Skip to content

Add V1 REST API Reference docs for OpenHands Cloud#460

Draft
jpelletier1 wants to merge 4 commits intomainfrom
add-v1-api-reference
Draft

Add V1 REST API Reference docs for OpenHands Cloud#460
jpelletier1 wants to merge 4 commits intomainfrom
add-v1-api-reference

Conversation

@jpelletier1
Copy link
Copy Markdown
Contributor

@jpelletier1 jpelletier1 commented Apr 19, 2026

  • I have read and reviewed the documentation changes to the best of my ability.
  • If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Summary of changes

This PR adds comprehensive API Reference documentation for the V1 REST API in OpenHands Cloud.

Changes

1. Created V1 OpenAPI Spec (openapi/V1_openapi.json)

  • Extracted 41 V1 API endpoints from the live OpenHands Cloud API (https://app.all-hands.dev/openapi.json)
  • Organized endpoints into logical categories with tags:
    • Conversations - Start, search, get, update, delete conversations
    • Sandboxes - Search, pause, resume sandbox execution environments
    • Configuration - List available models and settings
    • Users - Get current user info
    • Secrets - Manage custom secrets
    • Git - Search installations, repositories, branches
    • Skills - Search available skills
    • Webhooks - Event webhook endpoints

2. Updated Navigation (docs.json)

  • Added V1 REST API Reference group under Cloud > Integrations > Cloud API
  • Configured to use the OpenAPI integration with openapi/V1_openapi.json

3. Enhanced V1 API Overview (openhands/usage/api/v1.mdx)

  • Updated title and description
  • Added authentication section with examples
  • Added comprehensive endpoint tables for all resource types
  • Added a complete quick start Python example

Screenshots

The new API reference pages follow the same interactive format as the existing V0 API reference (like /api-reference/list-supported-models), with:

  • Endpoint path and method
  • Description and authentication requirements
  • Request parameters and body schema
  • Response schema with field descriptions
  • "Try it" button for interactive testing

This PR was created by an AI assistant (OpenHands) on behalf of the user.

@jpelletier1 can click here to continue refining the PR

@openhands-agent
Add V1 REST API Reference docs for OpenHands Cloud
00fa0ad 
- Create V1_openapi.json with 41 V1 API endpoints extracted from
  the live OpenHands Cloud API (https://app.all-hands.dev/openapi.json)
- Add V1 REST API Reference section to Cloud tab in docs.json
- Update openhands/usage/api/v1.mdx with comprehensive overview
  including authentication, key resources table, and quick start example

The V1 API reference includes:
- Conversations: Start, search, get, update, delete conversations
- Sandboxes: Search, pause, resume sandbox execution environments
- Configuration: List available models and settings
- Users: Get current user info
- Secrets: Manage custom secrets
- Git: Search installations, repositories, branches
- Skills: Search available skills
- Webhooks: Event webhook endpoints

Co-authored-by: openhands <openhands@all-hands.dev>
@mintlify
Copy link
Copy Markdown

mintlify Bot commented Apr 19, 2026 •
edited
Loading

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
all-hands-ai 🟢 Ready View Preview Apr 19, 2026, 11:38 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@jpelletier1 jpelletier1 requested a review from tofarr April 19, 2026 11:39
@jpelletier1
Copy link
Copy Markdown
Contributor Author

jpelletier1 commented Apr 19, 2026

@tofarr might be the best person to review these docs. I had OpenHands write them using what's published here: https://app.all-hands.dev/openapi.json

Preview location: https://allhandsai-add-v1-api-reference.mintlify.app/api-reference/conversations/search-conversation-events

@jpelletier1
Copy link
Copy Markdown
Contributor Author

jpelletier1 commented Apr 19, 2026

@OpenHands Please make these changes

  • update the "OpenHands API Reference" link under /openhands/usage/cloud/cloud-api to the new V1 API reference
  • remove the Documentation > Additional Documentation > V0 Reference > V0 REST API page from the navigation

@openhands-ai
Copy link
Copy Markdown

openhands-ai Bot commented Apr 19, 2026

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

@openhands-agent
Update API reference link to V1 and remove V0 REST API from nav
0a03868 
- Update cloud-api.mdx to link to V1 REST API Reference
- Remove V0 REST API group from Documentation > Additional Documentation > V0 Reference

Co-authored-by: openhands <openhands@all-hands.dev>
@openhands-ai
Copy link
Copy Markdown

openhands-ai Bot commented Apr 19, 2026

Summary of Changes

I addressed the PR comment from @jpelletier1 with the following changes:

Checklist of Requested Changes

✅ Update the "OpenHands API Reference" link under /openhands/usage/cloud/cloud-api

  • Changed the link from https://docs.openhands.dev/api-reference to /openhands/usage/api/v1 (the new V1 REST API Reference page)

✅ Remove the Documentation > Additional Documentation > V0 Reference > V0 REST API page from navigation

  • Removed the V0 REST API group from docs.json that referenced openapi/V0_openapi.json

Changes Made

  • 2 files modified: docs.json and openhands/usage/cloud/cloud-api.mdx
  • Net change: -4 lines (removed unnecessary V0 REST API navigation entry)

Conciseness

The changes are minimal and focused solely on the two requested modifications. No extraneous changes were made.

Status

Committed and pushed to the add-v1-api-reference branch. PR #460 is now updated and the Mintlify preview will reflect these changes.

@jpelletier1
Copy link
Copy Markdown
Contributor Author

jpelletier1 commented Apr 19, 2026

@OpenHands Replace the "Quick Start Example" in openhands/usage/api/v1 with the "API Usage Example (V1)" under /openhands/usage/cloud/cloud-api

Then, remove /openhands/usage/cloud/cloud-api and use openhands/usage/api/v1 as the main overview page.

@openhands-ai
Copy link
Copy Markdown

openhands-ai Bot commented Apr 19, 2026

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

@openhands-agent
Consolidate Cloud API docs into V1 API Reference overview
89310e6 
- Replace quick start example in v1.mdx with comprehensive API Usage Example from cloud-api.mdx
- Add streaming, status polling, and legacy V0 migration sections to v1.mdx
- Remove cloud-api.mdx (now consolidated into v1.mdx)
- Update docs.json to use v1.mdx as the main Cloud API overview page
- Update all internal links from /openhands/usage/cloud/cloud-api to /openhands/usage/api/v1

Co-authored-by: openhands <openhands@all-hands.dev>
@openhands-ai
Copy link
Copy Markdown

openhands-ai Bot commented Apr 19, 2026

Summary of Changes

I addressed the PR comment from @jpelletier1 requesting to consolidate the Cloud API documentation.

Checklist of Requested Changes

✅ Replace the "Quick Start Example" in openhands/usage/api/v1 with the "API Usage Example (V1)" from /openhands/usage/cloud/cloud-api

  • Replaced the simple Python-only quick start with the comprehensive multi-language example (cURL, Python, TypeScript)
  • Added all the detailed sections: streaming, status polling, status field references, complete polling example, listing conversations, rate limits, V0-to-V1 migration guide, and legacy V0 documentation

✅ Remove /openhands/usage/cloud/cloud-api and use openhands/usage/api/v1 as the main overview page

  • Deleted openhands/usage/cloud/cloud-api.mdx
  • Updated docs.json to use openhands/usage/api/v1 as the first page under the "Cloud API" group

Additional Necessary Changes

  • Updated 8 files with internal links that referenced /openhands/usage/cloud/cloud-api to point to /openhands/usage/api/v1
  • Enhanced the API key creation instructions in v1.mdx to include the more detailed steps (direct link to settings, note about key being shown once)

Conciseness

All changes are directly related to the consolidation request. No extraneous changes were made.

Commit: 89310e6 - "Consolidate Cloud API docs into V1 API Reference overview"
PR: #460

@jpelletier1
Copy link
Copy Markdown
Contributor Author

jpelletier1 commented Apr 21, 2026

@OpenHands in openhands/usage/api/v1 under the "API Usage Example (V1)" section, can you create an example for resuming a conversation?

@openhands-ai
Copy link
Copy Markdown

openhands-ai Bot commented Apr 21, 2026

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

@openhands-agent
Add example for resuming a conversation
1cc7e5c 
Add a 'Resuming a Conversation' example section under API Usage Example (V1)
that demonstrates how to use the sandbox resume endpoint to resume a
paused conversation. Includes cURL, Python, and TypeScript code examples
in multi-tab format.
@openhands-ai
Copy link
Copy Markdown

openhands-ai Bot commented Apr 21, 2026

Work Completed:

  1. ✅ Request fully addressed - Added a "Resuming a Conversation" example section in openhands/usage/api/v1.mdx under the "API Usage Example (V1)" section as requested by @jpelletier1

  2. ✅ Changes are concise - Added only the new example section (73 lines) with cURL, Python, and TypeScript code examples in the standard multi-tab format used throughout the document

  3. Summary of changes:

    • Added new section demonstrating how to use POST /api/v1/sandboxes/{sandbox_id}/resume to resume a paused conversation
    • Included instructions on obtaining the sandbox_id from conversation details
    • Committed and pushed to branch add-v1-api-reference (PR Add V1 REST API Reference docs for OpenHands Cloud #460)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tofarr tofarr Awaiting requested review from tofarr

@mamoodi mamoodi Awaiting requested review from mamoodi mamoodi will be requested when the pull request is marked ready for review mamoodi is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jpelletier1 @openhands-agent