mvp-factory-setups/openhands-api-reference.md

# 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:**
```json
{
  "initial_user_msg": "Your task here",
  "repository": null,
  "selected_branch": null,
  "git_provider": null
}
```

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
[
  "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:
- **Model:** openai/MiniMax-M2
- **API Base:** https://api.minimax.chat/v1/text/chatcompletion_v2
- **Runtime Image:** docker.openhands.dev/openhands/runtime:latest-nikolaik
- **Default Workspace:** /workspace (inside container)

### Environment Variables (configured in systemd):
```bash
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
```bash
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
```bash
CONV_ID="your-conversation-id-here"
curl http://localhost:3000/api/conversations/${CONV_ID}
```

### Test 3: Get Events
```bash
curl "http://localhost:3000/api/conversations/${CONV_ID}/events?limit=10"
```

### Test 4: Send Additional Message
```bash
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

- **Swagger UI:** http://localhost:3000/docs
- **OpenAPI Spec:** http://localhost:3000/openapi.json
- **OpenHands Docs:** https://docs.openhands.dev
- **Server Status:** `sudo systemctl status openhands.service`
- **Server Logs:** `sudo journalctl -u openhands.service -f`

---

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