Skip to content

Comments

docs: Update Cloud API documentation to use V1 endpoint#349

Merged
neubig merged 3 commits intomainfrom
docs/cloud-api-v1-migration
Feb 20, 2026
Merged

docs: Update Cloud API documentation to use V1 endpoint#349
neubig merged 3 commits intomainfrom
docs/cloud-api-v1-migration

Conversation

@neubig
Copy link
Contributor

@neubig neubig commented Feb 19, 2026

Summary

This PR updates the Cloud API documentation to recommend and document the V1 API endpoint (/api/v1/app-conversations) instead of the deprecated V0 endpoint (/api/conversations).

Changes

New V1 API Documentation

  • Updated the primary documentation to use the V1 endpoint
  • Documented the new request format with initial_message.content array
  • Documented the new response format (start task with status progression)
  • Added documentation for the streaming endpoint (/api/v1/app-conversations/stream-start)

Migration Guide

  • Added a clear migration section explaining the differences between V0 and V1
  • Provided a comparison table of field names and formats
  • Listed step-by-step migration instructions

V0 API Deprecation

  • Kept the V0 API documentation but marked it as deprecated
  • Added warning notices about the April 1, 2026 removal date
  • Maintained backward compatibility for users still on V0

Key Differences

Feature V0 API V1 API
Endpoint POST /api/conversations POST /api/v1/app-conversations
Message format initial_user_msg (string) initial_message.content (array)
Repository field repository selected_repository
Response Immediate conversation_id Start task with status and app_conversation_id

Testing

The V1 API was tested using a real API key:

  • Successfully created a conversation via POST /api/v1/app-conversations
  • Verified the response contains proper id, status, and eventually app_conversation_id
  • Confirmed the conversation reached READY status and execution_status: finished

References

  • V1 API source: openhands/app_server/app_conversation/app_conversation_router.py
  • V0 API source (deprecated): openhands/server/routes/manage_conversations.py
  • V0 deprecation notice in source: "Deprecated since version 1.0.0, scheduled for removal April 1, 2026"

@neubig can click here to continue refining the PR

@openhands-agent
docs: Update Cloud API documentation to use V1 endpoint
3b00e6d 
- Add V1 API documentation as the primary/recommended approach
- Document the new request format (initial_message with content array)
- Document the new response format (start task with status progression)
- Add migration guide from V0 to V1 API
- Keep V0 API documentation with deprecation warnings
- Note V0 API removal scheduled for April 1, 2026

The V1 API provides better conversation lifecycle management with
status updates during startup (WORKING -> READY).

Co-authored-by: openhands <openhands@all-hands.dev>
jlav
jlav reviewed Feb 19, 2026
View reviewed changes
openhands/usage/cloud/cloud-api.mdx
## Migrating from V0 to V1 API

<Warning>
The V0 API (`/api/conversations`) is deprecated and scheduled for removal on **April 1, 2026**.
Copy link

@jlav jlav Feb 19, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did we ever send any comms about about the April 1 date? I know there are references in the code to an April 1 removal date, but unless all our API users are keenly watching our codebase...

Copy link
Contributor Author

@neubig neubig Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we sent any comms, maybe we should. But at least this is better than in the codebase.

@neubig neubig requested a review from jlav February 19, 2026 21:51
@neubig neubig marked this pull request as ready for review February 19, 2026 21:51
@neubig neubig requested a review from mamoodi as a code owner February 19, 2026 21:51
all-hands-bot
all-hands-bot reviewed Feb 19, 2026
View reviewed changes
Copy link
Contributor

@all-hands-bot all-hands-bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Acceptable - Good migration guide and clear examples, but needs formatting fixes and clarification on response fields.

jlav
jlav approved these changes Feb 19, 2026
View reviewed changes
Copy link

@jlav jlav left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The one comment about app_conversation_id is true and should be resolved, but otherwise LGTM.

@neubig
Copy link
Contributor Author

neubig commented Feb 19, 2026

@OpenHands check the review comments, fix them if they are worth fixing, and mark them resolved using the graphql api

@openhands-ai
Copy link

openhands-ai bot commented Feb 19, 2026

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

@openhands-agent
docs: Add streaming response format example
8f0a789 
Address review comment by adding an example of the streaming response format
for the /api/v1/app-conversations/stream-start endpoint.

Co-authored-by: openhands <openhands@all-hands.dev>
@openhands-agent
docs: Fix indentation in Tab components
20b98d9 
Fix indentation issues with </Tab> closing tags (4 spaces -> 2 spaces),
<Tab> opening tags (4 spaces -> 2 spaces), and code blocks (8 spaces -> 4 spaces)
in both V1 and V0 API example sections.

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

openhands-ai bot commented Feb 19, 2026

Summary of Work Completed

I reviewed the PR comments on PR #349, fixed the actionable issues, pushed the changes, and resolved the review threads via the GitHub GraphQL API.

Changes Made (2 commits pushed to docs/cloud-api-v1-migration)

Commit 1: 8f0a789 - Add streaming response format example

  • Added example JSON showing the streaming endpoint response format with progressive status updates (WORKING → WAITING_FOR_SANDBOX → PREPARING_REPOSITORY → READY)
  • Addresses the "Missing example" suggestion from all-hands-bot

Commit 2: 20b98d9 - Fix indentation in Tab components

  • Fixed </Tab> closing tags: 4 spaces → 2 spaces
  • Fixed <Tab> opening tags: 4 spaces → 2 spaces
  • Fixed code blocks inside tabs: 8 spaces → 4 spaces
  • Applied to both V1 and V0 API sections for consistency

Review Threads Resolved

✅ 6 of 7 review threads were resolved via GraphQL API:

  • Missing streaming example
  • Indentation issues (3 threads)
  • Response clarity (jlav confirmed correct)
  • Positive feedback ("Good catch")

Left Unresolved

The April 1 deprecation date discussion thread was intentionally left unresolved as it's a business communication question between team members, not a code change request.

Checklist

  • Identified and fixed actionable review comments
  • Changes are minimal and directly address the feedback
  • Commits pushed to remote branch
  • Review threads marked as resolved using GraphQL API

@neubig neubig merged commit 5dae689 into main Feb 20, 2026
5 checks passed
@neubig neubig deleted the docs/cloud-api-v1-migration branch February 20, 2026 01:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@all-hands-bot all-hands-bot all-hands-bot left review comments

@jlav jlav jlav approved these changes

@mamoodi mamoodi Awaiting requested review from mamoodi mamoodi is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@neubig @jlav @all-hands-bot @openhands-agent