OpenHands Conversations API
The Conversations API from OpenHands — 16 operation(s) for conversations.
The Conversations API from OpenHands — 16 operation(s) for conversations.
openapi: 3.1.0
info:
title: OpenHands Add Git Providers Conversations API
description: 'OpenHands: Code Less, Make More'
version: 0.53.0
servers:
- url: https://app.all-hands.dev
description: Production server
- url: http://localhost:3000
description: Local development server
tags:
- name: Conversations
paths:
/api/conversations/{conversation_id}/list-files:
get:
summary: List Workspace Files
description: List workspace files visible to the conversation runtime. Applies .gitignore and internal ignore rules.
operationId: list_files_api_conversations__conversation_id__list_files_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
- name: path
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Path
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
type: string
title: Response List Files Api Conversations Conversation Id List Files Get
'404':
description: Runtime not initialized
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response 404 List Files Api Conversations Conversation Id List Files Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'500':
description: Error listing or filtering files
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response 500 List Files Api Conversations Conversation Id List Files Get
tags:
- Conversations
/api/conversations/{conversation_id}/select-file:
get:
summary: Get File Content
description: Return the content of the given file from the conversation workspace.
operationId: select_file_api_conversations__conversation_id__select_file_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
- name: file
in: query
required: true
schema:
type: string
title: File
responses:
'200':
description: File content returned as JSON
content:
application/json:
schema:
type: object
additionalProperties:
type: string
title: Response 200 Select File Api Conversations Conversation Id Select File Get
'415':
description: Unsupported media type
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response 415 Select File Api Conversations Conversation Id Select File Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'500':
description: Error opening file
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response 500 Select File Api Conversations Conversation Id Select File Get
tags:
- Conversations
/api/conversations/{conversation_id}/zip-directory:
get:
summary: Download Workspace Archive
operationId: zip_current_workspace_api_conversations__conversation_id__zip_directory_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Zipped workspace returned as FileResponse
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'500':
description: Error zipping workspace
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response 500 Zip Current Workspace Api Conversations Conversation Id Zip Directory Get
description: Return a ZIP archive of the current conversation workspace.
tags:
- Conversations
/api/conversations/{conversation_id}/git/changes:
get:
summary: Git Changes
operationId: git_changes_api_conversations__conversation_id__git_changes_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties:
type: string
title: Response Git Changes Api Conversations Conversation Id Git Changes Get
'404':
description: Not a git repository
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response 404 Git Changes Api Conversations Conversation Id Git Changes Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'500':
description: Error getting changes
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response 500 Git Changes Api Conversations Conversation Id Git Changes Get
tags:
- Conversations
/api/conversations/{conversation_id}/git/diff:
get:
summary: Git Diff
operationId: git_diff_api_conversations__conversation_id__git_diff_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
- name: path
in: query
required: true
schema:
type: string
title: Path
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Git Diff Api Conversations Conversation Id Git Diff Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'500':
description: Error getting diff
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response 500 Git Diff Api Conversations Conversation Id Git Diff Get
tags:
- Conversations
/api/conversations/{conversation_id}/upload-files:
post:
summary: Upload Files
operationId: upload_files_api_conversations__conversation_id__upload_files_post
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_upload_files_api_conversations__conversation_id__upload_files_post'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/POSTUploadFilesModel'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations/{conversation_id}/submit-feedback:
post:
summary: Submit Feedback
description: 'Submit user feedback.
This function stores the provided feedback data.
To submit feedback:'
operationId: submit_feedback_api_conversations__conversation_id__submit_feedback_post
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations/{conversation_id}/config:
get:
summary: Get Remote Runtime Config
description: 'Retrieve the runtime configuration.
Currently, this is the session ID and runtime ID (if available).'
operationId: get_remote_runtime_config_api_conversations__conversation_id__config_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations/{conversation_id}/events:
get:
summary: Search Events
description: Search through the event stream with filtering and pagination.
operationId: search_events_api_conversations__conversation_id__events_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
- name: start_id
in: query
required: false
schema:
type: integer
default: 0
title: Start Id
- name: end_id
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
title: End Id
- name: reverse
in: query
required: false
schema:
type: boolean
default: false
title: Reverse
- name: limit
in: query
required: false
schema:
type: integer
default: 20
title: Limit
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/EventFilter'
- type: 'null'
title: Filter
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
post:
summary: Add Event
operationId: add_event_api_conversations__conversation_id__events_post
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations/{conversation_id}/microagents:
get:
summary: Get Microagents
description: 'Get all microagents associated with the conversation.
This endpoint returns all repository and knowledge microagents that are loaded for the conversation.'
operationId: get_microagents_api_conversations__conversation_id__microagents_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations:
post:
summary: New Conversation
description: 'Initialize a new session or join an existing one.
After successful initialization, the client should connect to the WebSocket
using the returned conversation ID.'
operationId: new_conversation_api_conversations_post
security:
- APIKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitSessionRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
get:
summary: Search Conversations
operationId: search_conversations_api_conversations_get
security:
- APIKeyHeader: []
parameters:
- name: page_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Page Id
- name: limit
in: query
required: false
schema:
type: integer
default: 20
title: Limit
- name: selected_repository
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Selected Repository
- name: conversation_trigger
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/ConversationTrigger'
- type: 'null'
title: Conversation Trigger
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationInfoResultSet'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations/{conversation_id}:
get:
summary: Get Conversation
operationId: get_conversation_api_conversations__conversation_id__get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ConversationInfo'
- type: 'null'
title: Response Get Conversation Api Conversations Conversation Id Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
delete:
summary: Delete Conversation
operationId: delete_conversation_api_conversations__conversation_id__delete
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: boolean
title: Response Delete Conversation Api Conversations Conversation Id Delete
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
patch:
summary: Update Conversation
description: 'Update conversation metadata.
This endpoint allows updating conversation details like title.
Only the conversation owner can update the conversation.'
operationId: update_conversation_api_conversations__conversation_id__patch
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateConversationRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: boolean
title: Response Update Conversation Api Conversations Conversation Id Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations/{conversation_id}/remember-prompt:
get:
summary: Get Prompt
operationId: get_prompt_api_conversations__conversation_id__remember_prompt_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
- name: event_id
in: query
required: true
schema:
type: integer
title: Event Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations/{conversation_id}/start:
post:
summary: Start Conversation
description: 'Start an agent loop for a conversation.
This endpoint calls the conversation_manager''s maybe_start_agent_loop method
to start a conversation. If the conversation is already running, it will
return the existing agent loop info.'
operationId: start_conversation_api_conversations__conversation_id__start_post
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProvidersSetModel'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations/{conversation_id}/stop:
post:
summary: Stop Conversation
description: 'Stop an agent loop for a conversation.
This endpoint calls the conversation_manager''s close_session method
to stop a conversation.'
operationId: stop_conversation_api_conversations__conversation_id__stop_post
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
/api/conversations/{conversation_id}/trajectory:
get:
summary: Get Trajectory
description: 'Get trajectory.
This function retrieves the current trajectory and returns it.'
operationId: get_trajectory_api_conversations__conversation_id__trajectory_get
security:
- APIKeyHeader: []
parameters:
- name: conversation_id
in: path
required: true
schema:
type: string
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
tags:
- Conversations
components:
schemas:
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ProvidersSetModel:
properties:
providers_set:
anyOf:
- items:
$ref: '#/components/schemas/ProviderType'
type: array
- type: 'null'
title: Providers Set
type: object
title: ProvidersSetModel
MCPSHTTPServerConfig:
properties:
url:
type: string
title: Url
api_key:
anyOf:
- type: string
- type: 'null'
title: Api Key
type: object
required:
- url
title: MCPSHTTPServerConfig
POSTUploadFilesModel:
properties:
file_urls:
items:
type: string
type: array
title: File Urls
skipped_files:
items:
type: string
type: array
title: Skipped Files
type: object
required:
- file_urls
- skipped_files
title: POSTUploadFilesModel
description: Upload files response model
RuntimeStatus:
type: string
enum:
- STATUS$STOPPED
- STATUS$BUILDING_RUNTIME
- STATUS$STARTING_RUNTIME
- STATUS$RUNTIME_STARTED
- STATUS$SETTING_UP_WORKSPACE
- STATUS$SETTING_UP_GIT_HOOKS
- STATUS$READY
- STATUS$ERROR
- STATUS$ERROR_RUNTIME_DISCONNECTED
- STATUS$ERROR_LLM_AUTHENTICATION
- STATUS$ERROR_LLM_SERVICE_UNAVAILABLE
- STATUS$ERROR_LLM_INTERNAL_SERVER_ERROR
- STATUS$ERROR_LLM_OUT_OF_CREDITS
- STATUS$ERROR_LLM_CONTENT_POLICY_VIOLATION
- CHAT_INTERFACE$AGENT_RATE_LIMITED_STOPPED_MESSAGE
- STATUS$GIT_PROVIDER_AUTHENTICATION_ERROR
- STATUS$LLM_RETRY
- STATUS$ERROR_MEMORY
title: RuntimeStatus
UpdateConversationRequest:
properties:
title:
type: string
maxLength: 200
minLength: 1
title: Title
description: New conversation title
additionalProperties: false
type: object
required:
- title
title: UpdateConversationRequest
description: Request model for updating conversation metadata.
EventFilter:
properties:
exclude_hidden:
type: boolean
title: Exclude Hidden
default: false
query:
anyOf:
- type: string
- type: 'null'
title: Query
include_types:
anyOf:
- items: {}
type: array
- type: 'null'
title: Include Types
exclude_types:
anyOf:
- items: {}
type: array
- type: 'null'
title: Exclude Types
source:
anyOf:
- type: string
- type: 'null'
title: Source
start_date:
anyOf:
- type: string
- type: 'null'
title: Start Date
end_date:
anyOf:
- type: string
- type: 'null'
title: End Date
type: object
title: EventFilter
InitSessionRequest:
properties:
repository:
anyOf:
- type: string
- type: 'null'
title: Repository
git_provider:
anyOf:
- $ref: '#/components/schemas/ProviderType'
- type: 'null'
selected_branch:
anyOf:
- type: string
- type: 'null'
title: Selected Branch
initial_user_msg:
anyOf:
- type: string
- type: 'null'
title: Initial User Msg
image_urls:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Image Urls
replay_json:
anyOf:
- type: string
- type: 'null'
title: Replay Json
suggested_task:
anyOf:
- $ref: '#/components/schemas/SuggestedTask'
- type: 'null'
create_microagent:
anyOf:
- $ref: '#/components/schemas/CreateMicroagent'
- type: 'null'
conversation_instructions:
anyOf:
- type: string
- type: 'null'
title: Conversation Instructions
mcp_config:
anyOf:
- $ref: '#/components/schemas/MCPConfig'
- type: 'null'
conversation_id:
type: string
title: Conversation Id
additionalProperties: false
type: object
title: InitSessionRequest
TaskType:
type: string
enum:
- MERGE_CONFLICTS
- FAILING_CHECKS
- UNRESOLVED_COMMENTS
- OPEN_ISSUE
- OPEN_PR
- CREATE_MICROAGENT
title: TaskType
ConversationStatus:
type: string
enum:
- STARTING
- RUNNING
- STOPPED
title: ConversationStatus
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
ProviderType:
type: string
enum:
- github
- gitlab
- bitbucket
- enterprise_sso
title: ProviderType
CreateMicroagent:
properties:
repo:
type: string
title: Repo
git_provider:
anyOf:
- $ref: '#/components/schemas/ProviderType'
- type: 'null'
title:
anyOf:
- type: string
- type: 'null'
title: Title
type: object
required:
- repo
title: CreateMicroagent
MCPSSEServerConfig:
properties:
url:
type: string
title: Url
api_key:
anyOf:
- type: string
- type: 'null'
title: Api Key
type: object
required:
- url
title: MCPSSEServerConfig
description: "Configuration for a single MCP server.\n\nAttributes:\n url: The server URL\n api_key: Optional API key for authentication"
ConversationInfoResultSet:
properties:
results:
items:
$ref: '#/components/schemas/ConversationInfo'
type: array
title: Results
next_page_id:
anyOf:
- type: string
- type: 'null'
title: Next Page Id
type: object
title: ConversationInfoResultSet
Body_upload_files_api_conversations__conversation_id__upload_files_post:
properties:
files:
items:
type: string
format: binary
type: array
title: Files
type: object
required:
- files
title: Body_upload_files_api_conversations__conversation_id__upload_files_post
SuggestedTask:
properties:
git_provider:
$ref: '#/components/schemas/ProviderType'
task_type:
$ref: '#/components/schemas/TaskType'
repo:
type: string
title: Repo
issue_number:
type: integer
title: Issue Number
title:
type: string
title: Title
type: object
required:
- git_provider
- task_type
- repo
- issue_number
- title
title: SuggestedTask
ConversationTrigger:
type: string
enum:
- resolver
- gui
- suggested_task
- openhands_api
- slack
- microagent_management
- jira
- jira_dc
- linear
title: ConversationTrigger
MCPConfig:
properties:
sse_servers:
items:
$ref: '#/components/schemas/MCPSSEServerConfig'
type: array
title: Sse Servers
stdio_servers:
items:
$ref: '#/components/schemas/MCPStdioServerConfig'
type: array
title: Stdio Servers
shttp_servers:
items:
$ref: '#/components/schemas/MCPSHTTPServerConfig'
type: array
title: Shttp Servers
additionalProperties: false
type: object
title: MCPConfig
description: "Configuration for MCP (Message Control Protocol) settings.\n\nAttributes:\n sse_servers: List of MCP SSE server configs\n stdio_servers: List of MCP stdio server configs. These servers will be added to the MCP Router running inside runtime container.\n shttp_servers: List of MCP HTTP server configs."
MCPStdioServerConfig:
properties:
name:
type: string
title: Name
command:
type: string
title: Command
args:
items:
type: string
type: array
title: Args
env:
additionalProperties:
type: string
type: object
title: Env
type: object
required:
- name
- command
title
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openhands/refs/heads/main/openapi/openhands-conversations-api-openapi.yml