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: MCPStdioServerConfig description: "Configuration for a MCP server that uses stdio.\n\nAttributes:\n name: The name of the server\n command: The command to run the server\n args: The arguments to pass to the server\n env: The environment variables to set for the server" ConversationResponse: properties: status: type: string title: Status conversation_id: type: string title: Conversation Id message: anyOf: - type: string - type: 'null' title: Message conversation_status: anyOf: - $ref: '#/components/schemas/ConversationStatus' - type: 'null' type: object required: - status - conversation_id title: ConversationResponse ConversationInfo: properties: conversation_id: type: string title: Conversation Id title: type: string title: Title last_updated_at: anyOf: - type: string format: date-time - type: 'null' title: Last Updated At status: $ref: '#/components/schemas/ConversationStatus' default: STOPPED runtime_status: anyOf: - $ref: '#/components/schemas/RuntimeStatus' - type: 'null' selected_repository: anyOf: - type: string - type: 'null' title: Selected Repository selected_branch: anyOf: - type: string - type: 'null' title: Selected Branch git_provider: anyOf: - $ref: '#/components/schemas/ProviderType' - type: 'null' trigger: anyOf: - $ref: '#/components/schemas/ConversationTrigger' - type: 'null' num_connections: type: integer title: Num Connections default: 0 url: anyOf: - type: string - type: 'null' title: Url session_api_key: anyOf: - type: string - type: 'null' title: Session Api Key created_at: type: string format: date-time title: Created At pr_number: items: type: integer type: array title: Pr Number type: object required: - conversation_id - title title: ConversationInfo securitySchemes: APIKeyHeader: type: apiKey in: header name: X-Session-API-Key