---
title: "Send chat message"
method: POST
path: "/api/chat"
tags: ["chat"]
---

# Send chat message

`POST /api/chat`

## Request

- Base URL: `https://localhost:8080`
- URL: `https://localhost:8080/api/chat`
- Auth: none declared

Sends a chat message and receives a complete AI response (non-streaming)

## Request body

- ChatRequestDto
  - `messages` ChatMessageDto[]: Array of chat messages
    - `role` 'user' | 'assistant' | 'system', required: Message role
    - `content` string, required: Message content
    - `toolCalls` ToolCallDto[]: Tool calls (for assistant messages)
      - `toolCallId` string, required: Tool call ID
      - `toolName` string, required: Tool name
      - `args` object, required: Tool arguments
      - `sequenceOrder` number: Sequence order within message
    - `toolResults` ChatMessageToolResultDto[]: Tool results (for assistant messages)
      - `toolCallId` string, required: Tool call ID this result belongs to
      - `result` object: Tool execution result
      - `error` string: Error message if execution failed
      - `executionTimeMs` number: Execution time in milliseconds
  - `message` string: Single message string (alternative to messages array)
  - `model` string: AI model to use
  - `temperature` number: Temperature for AI response (0-2)
  - `sessionId` string: Session ID for conversation continuity
  - `clientId` string: Client ID for tracking
  - `clientMessageId` string: Stable id the client generates for THIS user message. Makes agent dispatch idempotent: a reconnect/retry that re-delivers the same chat:stream is ignored instead of spawning a second run. Absent for older clients.
  - `conversationId` string: Conversation ID to link message to existing conversation
  - `selectedFileIds` string[]: Document IDs to include in AI context
  - `attachmentIds` string[]: Attachment IDs to include as inline chat attachments
  - `documentContent` string: Current Word document content (sent by client, injected into user prompt)
  - `country` string: Jurisdiction: 2-letter country code (e.g. US, UK). Overrides user profile when set.
  - `circuitNames` string[]: Jurisdiction: circuit display names (e.g. "9th Circuit"). Overrides profile when set.
  - `stateNames` string[]: Jurisdiction: state display names (e.g. "California"). Overrides profile when set.
  - `subdivisionNames` string[]: Jurisdiction: subdivision names for non-US (e.g. "England & Wales"). Overrides profile when set.
  - `documentSnapshot` object: Lightweight snapshot of the current Word document (text + structure + indices). Used for reasoning and edit targeting. Optional and currently behind a feature flag.
  - `appContext` 'word' | 'outlook' | 'web' | 'docs' | 'email' | 'slack' | 'telegram' | 'whatsapp' | 'teams' | 'imessage' | 'mobile': Client application context — determines which tool set and system prompt the AI uses.
  - `docId` string: Host document identifier (for example, Google Docs docId when appContext = "docs").
  - `hostContext` object: Host/editor context from client (host, docId). When appContext is "docs", docId is normalized from here at entry if not set at top level.
  - `clientVersion` string: Add-in client version (e.g. Word add-in APP_VERSION). Sent only by clients that strip [[case:]] citation tags before display; gates whether the agent emits those tags. Absent ⇒ treated as an old client (no tags).
  - `editMode` 'auto' | 'approve' | 'answers_only': Editing posture for this turn. "answers_only" tells the backend to withhold the document-editing tools so the agent answers and researches in chat without modifying the document. Omitted/"auto"/"approve" leave editing available.
  - `openProposals` object[]: Word approval mode: the versioned suggested-edit cards still waiting in the panel when this message was sent (`OpenProposalCard`). Sent by add-in bundles that can revise an earlier turn's card; absent from older bundles. Read structurally by `readOpenProposals`.
  - `otherPendingSuggestions` number: Sent with `openProposals`: how many other suggested edits are waiting in the panel that cannot be revised in a later turn (formatting, document-end and pre-versioning cards).

## Response `200`

Chat response received successfully

- ChatResponseDto
  - `text` string, required: AI generated text response
  - `toolCalls` ToolCallDto[]: Array of tool calls requested by the AI
    - `toolCallId` string, required: Tool call ID
    - `toolName` string, required: Tool name
    - `args` object, required: Tool arguments
    - `sequenceOrder` number: Sequence order within message
  - `finishReason` string: Reason for finishing the response

## Other responses

- `400`: Invalid request data

---

[API](https://skmtc.dev/opencase/apis/opencase-backend-api.md) · [All operations](https://skmtc.dev/opencase/apis/opencase-backend-api/llms.txt) · [OpenAPI document](https://skmtc.dev/opencase/apis/opencase-backend-api/revisions/c66ef2d8dc00?raw)