gitadmin
/
mvp-factory-setups
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
mvp-factory-setups/openhands-api-reference.md

7.3 KiB
Raw Blame History

OpenHands API Reference for n8n Integration

Base URL: http://localhost:3000 API Version: 0.62.0 Documentation: http://localhost:3000/docs OpenAPI Spec: http://localhost:3000/openapi.json

🔑 Key Endpoints for n8n Automation

1. Create New Conversation

Endpoint: POST /api/conversations

Purpose: Initialize a new OpenHands session/conversation

Request Body:

{
  "initial_user_msg": "Your task here",
  "repository": null,
  "selected_branch": null,
  "git_provider": null
}

Response:

{
  "status": "ok",
  "conversation_id": "f0f3e760dca14af1b94d04d825aca43a",
  "message": null,
  "conversation_status": "STARTING"
}

Notes:

  • The conversation_id is required for all subsequent calls
  • conversation_status will be "STARTING" initially
  • Runtime container will be created automatically
  • First run takes 2-3 minutes to initialize

2. Get Conversation Status

Endpoint: GET /api/conversations/{conversation_id}

Purpose: Check the current status of a conversation

Response:

{
  "conversation_id": "f0f3e760dca14af1b94d04d825aca43a",
  "title": "Conversation f0f3e",
  "last_updated_at": "2025-11-29T19:23:46.858186Z",
  "status": "STARTING",
  "runtime_status": "STATUS$STARTING_RUNTIME",
  "selected_repository": null,
  "trigger": "gui",
  "num_connections": 0,
  "created_at": "2025-11-29T19:23:46.841828Z"
}

Status Values:

  • STARTING - Conversation is initializing
  • RUNNING - Agent is actively working
  • STOPPED - Conversation has ended
  • AWAITING_USER_INPUT - Waiting for user response

3. Get Conversation Events

Endpoint: GET /api/conversations/{conversation_id}/events

Purpose: Retrieve events/actions from the conversation (for monitoring progress)

Query Parameters:

  • limit (optional): Number of events to return
  • offset (optional): Event offset for pagination

Response:

{
  "events": [
    {
      "id": 0,
      "timestamp": "2025-11-29T19:23:46.850918",
      "source": "environment",
      "message": "",
      "observation": "agent_state_changed",
      "content": "",
      "extras": {
        "agent_state": "loading",
        "reason": ""
      }
    }
  ],
  "has_more": false
}

Event Types:

  • agent_state_changed - Agent status change
  • action - Agent performing an action
  • observation - System observation/response
  • message - User or assistant message

4. Send Message to Conversation

Endpoint: POST /api/conversations/{conversation_id}/message

Purpose: Add a new message/task to an existing conversation

Request Body:

{
  "content": "Your message or task here",
  "image_urls": []
}

Use Case: Send additional instructions or feedback to a running conversation

5. Start Conversation

Endpoint: POST /api/conversations/{conversation_id}/start

Purpose: Explicitly start the agent loop

Note: Usually auto-started if initial_user_msg is provided during creation

6. Stop Conversation

Endpoint: POST /api/conversations/{conversation_id}/stop

Purpose: Stop a running conversation/agent

Use Case: Cancel a long-running task or end the session

7. List All Conversations

Endpoint: GET /api/conversations

Purpose: Get a list of all conversations

Query Parameters:

  • page_size (optional): Number of results per page
  • page_id (optional): Pagination token

Response:

{
  "results": [
    {
      "conversation_id": "2394472401834b10b8550afe1be9f617",
      "title": "Conversation 23944",
      "last_updated_at": "2025-11-28T16:35:31.804925Z",
      "status": "STOPPED",
      "created_at": "2025-11-28T16:35:31.789194Z"
    }
  ],
  "next_page_id": null
}

8. Get Available Models

Endpoint: GET /api/options/models

Purpose: List all supported LLM models

Response: Array of 1000+ model names (MiniMax, OpenAI, Claude, Gemini, etc.)

9. Get Available Agents

Endpoint: GET /api/options/agents

Purpose: List available agent types

Response:

[
  "BrowsingAgent",
  "CodeActAgent",
  "DummyAgent",
  "LocAgent",
  "ReadOnlyAgent",
  "VisualBrowsingAgent"
]

🔄 Typical Workflow for n8n

Simple One-Shot Task:

1. POST /api/conversations
   → Get conversation_id

2. Poll GET /api/conversations/{id}
   → Wait for status != "STARTING"

3. Poll GET /api/conversations/{id}/events
   → Monitor progress
   → Check for completion or errors

4. When done, optionally POST /api/conversations/{id}/stop

With Repository:

1. POST /api/conversations with repository URL
   → Get conversation_id

2. Wait for runtime initialization

3. POST /api/conversations/{id}/message
   → "Run npm install && npm test && npm build"

4. Poll events for results

5. On failure, POST /api/conversations/{id}/message
   → Send error feedback for retry

⚙️ Configuration

Current Server Config:

Environment Variables (configured in systemd):

LLM_MODEL=openai/MiniMax-M2
LLM_API_KEY=${MINIMAX_API_KEY}
LLM_BASE_URL=https://api.minimax.chat/v1/text/chatcompletion_v2
SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.openhands.dev/openhands/runtime:latest-nikolaik
LOG_ALL_EVENTS=true

🧪 Testing with curl

Test 1: Create Conversation

curl -X POST http://localhost:3000/api/conversations \
  -H "Content-Type: application/json" \
  -d '{"initial_user_msg": "Create a file named test.txt with content: Hello World"}'

Test 2: Check Status

CONV_ID="your-conversation-id-here"
curl http://localhost:3000/api/conversations/${CONV_ID}

Test 3: Get Events

curl "http://localhost:3000/api/conversations/${CONV_ID}/events?limit=10"

Test 4: Send Additional Message

curl -X POST http://localhost:3000/api/conversations/${CONV_ID}/message \
  -H "Content-Type: application/json" \
  -d '{"content": "Now create another file called test2.txt"}'

📊 Response Status Codes

  • 200 OK - Successful request
  • 422 Unprocessable Entity - Invalid request body
  • 404 Not Found - Conversation not found
  • 500 Internal Server Error - Server error

🐛 Common Issues

Issue: Conversation stuck in "STARTING"

  • Cause: Runtime container still initializing
  • Solution: Wait 2-3 minutes on first run, ~30s on subsequent runs
  • Check: docker logs openhands-runtime-{conversation_id}

Issue: "Field required" error

  • Cause: Missing required fields in request body
  • Solution: Check OpenAPI spec at /docs for exact schema

Issue: Events not updating

  • Cause: Agent may be waiting for runtime or processing
  • Solution: Poll events endpoint every 5-10 seconds

🔗 Additional Resources

Last Updated: 2025-11-29 Next Steps: Implement n8n workflow using these endpoints