> ## Documentation Index > Fetch the complete documentation index at: https://docs.agenhq.com/llms.txt > Use this file to discover all available pages before exploring further. # Send a user message to the agent in a session > Sends a new message from the user to the coding agent working in the session. The message is stored as a session event with the `user_message` type, then the agent either starts processing it immediately or the message is queued if the agent is already busy. Required API key scopes: any of `sessions:write`, `sessions:all`, `all:write`, `all:all`. ## OpenAPI ````yaml /coding-agent-api/openapi.json post /api/v1/sessions/{sessionId}/messages openapi: 3.1.0 info: title: Agen Coding Agent API version: 1.0.0 servers: - url: https://api.agenhq.com security: [] paths: /api/v1/sessions/{sessionId}/messages: post: tags: - Sessions summary: Send a user message to the agent in a session description: >- Sends a new message from the user to the coding agent working in the session. The message is stored as a session event with the `user_message` type, then the agent either starts processing it immediately or the message is queued if the agent is already busy. Required API key scopes: any of `sessions:write`, `sessions:all`, `all:write`, `all:all`. operationId: createSessionMessage parameters: - schema: minLength: 1 type: string in: path name: sessionId required: true requestBody: required: true content: application/json: schema: type: object required: - message properties: message: minLength: 1 type: string client_id: type: string responses: '200': description: Default Response content: application/json: schema: type: object required: - id - session_id - type - payload - status - client_id - session_goal_id - session_task_id - created_at - updated_at properties: id: type: string session_id: type: string type: enum: - user_message - agent_message - system_message - session_finished - session_closed - merge_request_merged - merge_request_closed - agent_file_tree_browse - agent_file_read - agent_file_edit - agent_file_create - agent_file_remove - agent_file_move - agent_file_copy - agent_file_read_range - agent_read_around_match - agent_search_files - agent_search_files_v2 - agent_plan_execution_update - agent_ask_user - user_ask_user_response - agent_branch_diff - agent_uncommitted_changes - agent_conflict_state - agent_check_target_branch_mergeability - agent_merge_remote_branch - agent_pull_from_remote - agent_push_to_remote - agent_abort_conflict_resolution - agent_rollback_uncommitted_changes - agent_http_request - agent_web_browse - agent_run_repository_command - agent_alert_created type: string payload: anyOf: - description: >- A message sent by the user to the agent within a session. This is the payload created by the send message endpoint. type: object required: - type - message properties: type: type: string enum: - user_message message: type: string - description: >- A chat message emitted by the agent during a session and shown in the session timeline. type: object required: - type - message properties: type: type: string enum: - agent_message message: type: string - description: >- A system-generated informational message shown in the session timeline. type: object required: - type - message properties: type: type: string enum: - system_message message: type: string - anyOf: - description: >- Indicates that the session was finished, including the actor who finished it. type: object required: - type - actor properties: type: type: string enum: - session_finished actor: type: object required: - id properties: id: type: string first_name: anyOf: - type: string - type: 'null' last_name: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' - description: >- Indicates that the session was closed, including the actor who closed it. type: object required: - type - actor properties: type: type: string enum: - session_closed actor: type: object required: - id properties: id: type: string first_name: anyOf: - type: string - type: 'null' last_name: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' - description: >- Indicates that the session merge request was merged, including the actor who merged it. type: object required: - type - actor properties: type: type: string enum: - merge_request_merged actor: type: object required: - id properties: id: type: string first_name: anyOf: - type: string - type: 'null' last_name: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' - description: >- Indicates that the session merge request was closed without merging, including the actor who closed it. type: object required: - type - actor properties: type: type: string enum: - merge_request_closed actor: type: object required: - id properties: id: type: string first_name: anyOf: - type: string - type: 'null' last_name: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' - description: >- Indicates that the agent browsed the repository file tree at a given path. type: object required: - type - repository_id - path properties: type: type: string enum: - agent_file_tree_browse repository_id: type: string path: type: string - description: >- Indicates that the agent read one or more files from a repository. type: object required: - type - repository_id - paths properties: type: type: string enum: - agent_file_read repository_id: type: string paths: type: array items: type: string - anyOf: - description: >- Indicates that the agent edited an existing file and includes the resulting diff. type: object required: - type - repository_id - file_path - diff properties: type: type: string enum: - agent_file_edit repository_id: type: string file_path: type: string diff: type: string - description: >- Indicates that the agent created a new file and includes the resulting diff. type: object required: - type - repository_id - file_path - diff properties: type: type: string enum: - agent_file_create repository_id: type: string file_path: type: string diff: type: string - description: >- Indicates that the agent removed a file from a repository. type: object required: - type - repository_id - file_path properties: type: type: string enum: - agent_file_remove repository_id: type: string file_path: type: string - anyOf: - description: >- Indicates that the agent moved or renamed a file within a repository. type: object required: - type - repository_id - source_path - destination_path properties: type: type: string enum: - agent_file_move repository_id: type: string source_path: type: string destination_path: type: string diff: type: string - description: >- Indicates that the agent copied a file within a repository. type: object required: - type - repository_id - source_path - destination_path properties: type: type: string enum: - agent_file_copy repository_id: type: string source_path: type: string destination_path: type: string diff: type: string - description: >- Indicates that the agent read a specific line range from a file. type: object required: - type - repository_id - path - start_line - end_line properties: type: type: string enum: - agent_file_read_range repository_id: type: string path: type: string start_line: type: number end_line: type: number - description: >- Indicates that the agent searched file contents and returned surrounding context for the matches. type: object required: - type - repository_id - query - path - matches properties: type: type: string enum: - agent_read_around_match repository_id: type: string query: type: string path: type: string include: type: string matches: type: array items: type: object required: - file - match_line - content properties: file: type: string match_line: type: number content: type: array items: type: object required: - line - content properties: line: type: number content: type: string - description: >- Indicates that the agent searched files for a query and returned matching results. type: object required: - type - repository_id - query properties: type: type: string enum: - agent_search_files repository_id: type: string query: type: string path: type: string include: type: string results: type: array items: type: object required: - file - line - content properties: file: type: string line: type: number content: type: string - description: >- Indicates that the agent ran multiple file searches and returned grouped results for each query item. type: object required: - type - repository_id - items properties: type: type: string enum: - agent_search_files_v2 repository_id: type: string items: type: array items: type: object required: - query properties: query: type: string path: type: string include: type: string results: type: array items: type: object required: - file - line - content properties: file: type: string line: type: number content: type: string - description: >- Indicates that the agent created or updated its execution plan, including the current goal and task list. type: object required: - type - goal_title - goal_id - tasks properties: type: type: string enum: - agent_plan_execution_update goal_title: type: string goal_id: type: string tasks: type: array items: type: object required: - id - title - status properties: id: type: string title: type: string status: type: string - description: >- Indicates that the agent asked the user one or more multiple-choice clarification questions. type: object required: - type - questions properties: type: type: string enum: - agent_ask_user questions: type: array items: type: object required: - question - topic - options properties: question: type: string topic: type: string options: type: array items: type: string - description: >- Indicates that the user responded to a previous ask-user question set from the agent. type: object required: - type - answers properties: type: type: string enum: - user_ask_user_response answers: type: array items: type: object required: - topic - answer properties: topic: type: string answer: type: string - description: >- Indicates that the agent inspected branch changes, either by listing changed files or returning a diff for a specific file. type: object required: - type - repository_id - action properties: type: type: string enum: - agent_branch_diff repository_id: type: string action: anyOf: - type: string enum: - list_files - type: string enum: - file_diff files: type: array items: type: object required: - path properties: path: type: string file_path: type: string diff: type: string - description: >- Indicates that the agent inspected the repository working tree and returned staged, unstaged, untracked, and conflict information. type: object required: - type - repository_id - branch - clean - staged - unstaged - untracked - conflict_state properties: type: type: string enum: - agent_uncommitted_changes repository_id: type: string branch: type: string clean: type: boolean staged: type: object required: - added - modified - deleted - renamed properties: added: type: array items: type: string modified: type: array items: type: string deleted: type: array items: type: string renamed: type: array items: type: object required: - from - to properties: from: type: string to: type: string unstaged: type: object required: - added - modified - deleted - renamed properties: added: type: array items: type: string modified: type: array items: type: string deleted: type: array items: type: string renamed: type: array items: type: object required: - from - to properties: from: type: string to: type: string untracked: type: array items: type: string conflict_state: type: object required: - conflicted - state properties: conflicted: type: array items: type: string state: type: object required: - merge - rebase - cherry_pick - revert properties: merge: type: boolean rebase: type: boolean cherry_pick: type: boolean revert: type: boolean diff: type: object required: - staged - unstaged - truncated properties: staged: type: string unstaged: type: string truncated: type: boolean - description: >- Indicates that the agent checked whether the repository is currently in a git conflict state. type: object required: - type - repository_id - branch - has_conflicts - conflicted_files - operation_state properties: type: type: string enum: - agent_conflict_state repository_id: type: string branch: type: string has_conflicts: type: boolean conflicted_files: type: array items: type: string operation_state: type: object required: - merge - rebase - cherry_pick - revert properties: merge: type: boolean rebase: type: boolean cherry_pick: type: boolean revert: type: boolean - description: >- Indicates that the agent checked whether the current branch can be merged with the target branch and whether conflicts would occur. type: object required: - type - repository_id - current_branch - target_branch - mergeable - has_conflicts - conflicted_files properties: type: type: string enum: - agent_check_target_branch_mergeability repository_id: type: string current_branch: type: string target_branch: type: string mergeable: type: boolean has_conflicts: type: boolean conflicted_files: type: array items: type: string - description: >- Indicates that the agent merged the target branch into the current branch to reproduce or resolve incoming changes. type: object required: - type - repository_id - current_branch - target_branch properties: type: type: string enum: - agent_merge_remote_branch repository_id: type: string current_branch: type: string target_branch: type: string - description: >- Indicates that the agent pulled changes from the remote branch and rebased the local branch onto them. type: object required: - type - repository_id - rebased - message properties: type: type: string enum: - agent_pull_from_remote repository_id: type: string rebased: type: boolean message: type: string branch: type: string before_sha: anyOf: - type: string - type: 'null' after_sha: anyOf: - type: string - type: 'null' remote: type: string - description: >- Indicates that the agent pushed committed changes from the current branch to the remote repository. type: object required: - type - repository_id - pushed - message properties: type: type: string enum: - agent_push_to_remote repository_id: type: string pushed: type: boolean message: type: string branch: type: string remote: type: string remote_ref: type: string - description: >- Indicates that the agent aborted an in-progress merge, rebase, cherry-pick, or revert conflict resolution flow. type: object required: - type - repository_id - aborted - aborted_operation - message properties: type: type: string enum: - agent_abort_conflict_resolution repository_id: type: string aborted: type: boolean aborted_operation: anyOf: - type: string enum: - merge - type: string enum: - rebase - type: string enum: - cherry-pick - type: string enum: - revert - type: 'null' message: type: string - description: >- Indicates that the agent discarded local uncommitted changes for the requested scope. type: object required: - type - repository_id - scope - rolled_back_paths - removed_untracked_paths - message properties: type: type: string enum: - agent_rollback_uncommitted_changes repository_id: type: string scope: anyOf: - type: string enum: - unstaged - type: string enum: - staged - type: string enum: - all rolled_back_paths: type: array items: type: string removed_untracked_paths: type: array items: type: string message: type: string - description: >- Indicates that the agent made an HTTP request to an external URL. type: object required: - type - url - method - status properties: type: type: string enum: - agent_http_request url: type: string method: type: string status: type: number - description: >- Indicates that the agent fetched and browsed a web page. type: object required: - type - url - status properties: type: type: string enum: - agent_web_browse url: type: string status: type: number - description: >- Indicates that the agent ran a command in a repository and includes the command output. type: object required: - type - repository_id - executable - args - exit_code - stdout - stderr - output - truncated properties: type: type: string enum: - agent_run_repository_command repository_id: type: string executable: enum: - node - npm - npx - yarn type: string args: type: array items: type: string working_directory: type: string exit_code: type: number stdout: type: string stderr: type: string output: type: string truncated: type: boolean - description: >- Indicates that the agent created an alert that requires human attention or follow-up. type: object required: - type - alert_id - level - status - title properties: type: type: string enum: - agent_alert_created alert_id: type: string level: type: string status: type: string title: type: string description: anyOf: - type: string - type: 'null' fingerprint: anyOf: - type: string - type: 'null' repository_id: anyOf: - type: string - type: 'null' repository_name: anyOf: - type: string - type: 'null' merge_request_id: anyOf: - type: string - type: 'null' scheduled_agent_run_id: anyOf: - type: string - type: 'null' occurrence_count: type: number status: enum: - completed - queued - processing - canceled type: string client_id: anyOf: - type: string - type: 'null' session_goal_id: anyOf: - type: string - type: 'null' session_task_id: anyOf: - type: string - type: 'null' created_at: type: string updated_at: type: string '400': description: Default Response content: application/json: schema: type: object required: - statusCode - code - error - message properties: statusCode: type: number code: type: string error: type: string message: type: string '401': description: Default Response content: application/json: schema: type: object required: - error properties: error: type: string '403': description: Default Response content: application/json: schema: type: object required: - error properties: error: type: string security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ````