---
title: "New Conversation"
method: POST
path: "/api/conversations"
---

# New Conversation

`POST /api/conversations`

Initialize a new session or join an existing one.

After successful initialization, the client should connect to the WebSocket
using the returned conversation ID.

## Request body

- InitSessionRequest
  - `repository` string, nullable
  - `git_provider` 'github' | 'gitlab' | 'bitbucket' | 'enterprise_sso'
  - `selected_branch` string, nullable
  - `initial_user_msg` string, nullable
  - `image_urls` string[], nullable
  - `replay_json` string, nullable
  - `suggested_task` SuggestedTask
    - `git_provider` 'github' | 'gitlab' | 'bitbucket' | 'enterprise_sso', required
    - `task_type` 'MERGE_CONFLICTS' | 'FAILING_CHECKS' | 'UNRESOLVED_COMMENTS' | 'OPEN_ISSUE' | 'OPEN_PR' | 'CREATE_MICROAGENT', required
    - `repo` string, required
    - `issue_number` integer, required
    - `title` string, required
  - `create_microagent` CreateMicroagent
    - `repo` string, required
    - `git_provider` 'github' | 'gitlab' | 'bitbucket' | 'enterprise_sso'
    - `title` string, nullable
  - `conversation_instructions` string, nullable
  - `mcp_config` MCPConfig — Configuration for MCP (Message Control Protocol) settings. Attributes: sse_servers: List of MCP SSE server configs stdio_servers: List of MCP stdio server configs. These servers will be added to the MCP Router running inside runtime container. shttp_servers: List of MCP HTTP server configs.
    - `sse_servers` MCPSSEServerConfig[]
      - `url` string, required
      - `api_key` string, nullable
    - `stdio_servers` MCPStdioServerConfig[]
      - `name` string, required
      - `command` string, required
      - `args` string[]
      - `env` object
    - `shttp_servers` MCPSHTTPServerConfig[]
      - `url` string, required
      - `api_key` string, nullable
  - `conversation_id` string

## Response `200`

Successful Response

- ConversationResponse
  - `status` string, required
  - `conversation_id` string, required
  - `message` string, nullable
  - `conversation_status` 'STARTING' | 'RUNNING' | 'STOPPED'

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/all-hands/apis/openhands.md) · [All operations](https://skmtc.dev/all-hands/apis/openhands/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/all-hands/openhands/revisions/4daa2bb4dbf1/schema)