Skip to main content
OpenHands is in a transition period: legacy (V0) endpoints still exist alongside the new /api/v1 endpoints.If you need the legacy OpenAPI reference, see the Legacy (V0) section in the Web tab.

​
Overview

OpenHands V1 REST endpoints are mounted under:
  • /api/v1
These endpoints back the current Web UI and are intended for newer integrations.

​
Key resources

The V1 API is organized around a few core concepts:
  • App conversations: create/list conversations and access conversation metadata.
    • POST /api/v1/app-conversations
    • GET /api/v1/app-conversations
  • Sandboxes: list/start/pause/resume the execution environments that power conversations.
    • GET /api/v1/sandboxes/search
    • POST /api/v1/sandboxes
    • POST /api/v1/sandboxes//pause
    • POST /api/v1/sandboxes//resume
  • Sandbox specs: list the available sandbox “templates” (e.g., Docker image presets).
    • GET /api/v1/sandbox-specs/search

​
Use Cases

​
Start Conversations from Plugins

The /launch route enables users to specify a plugin location (e.g., GitHub repo) and an initial message to run within OpenHands Cloud.
  • URL format (production): app.all-hands.dev/launch?plugins=BASE64_ENCODED_JSON&message=Optional%20message
  • URL format (simple): app.all-hands.dev/launch?plugin_source=github:owner/repo&plugin_ref=v1.0.0
  • PluginSpec structure:
    • source (string, required): Plugin source location (e.g., github:owner/repo, git URL, or local path)
    • ref (string, optional): Branch, tag, or commit reference
    • repo_path (string, optional): Subdirectory path within the repository
    • parameters (object, optional): User-provided configuration values
    • message (string, optional): Initial message to run with the plugin
  • Example: app.all-hands.dev/launch?plugins=W3sic291cmNlIjoiZ2l0aHViOm9wZW5oYW5kcy9leGFtcGxlLXBsdWdpbiIsInJlZiI6InYxLjAuMCJ9XQ==&message=Analyze%20this%20codebase