---
title: "Send a message to a chat session"
method: POST
path: "/chat/sessions/{session_id}/messages"
tags: ["Chat"]
---

# Send a message to a chat session

`POST /chat/sessions/{session_id}/messages`

## Request

- Base URL: `https://api-docs.jackhamr.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.jackhamr.ai/chat/sessions/{session_id}/messages`
- Auth: none declared

Send a user message to a chat session (REST only, no streaming).

Delegates to :func:`deliver_user_message_to_session`, the canonical
non-WebSocket send path also used by board-card "send to agent" and
gate-answer flows. That helper persists the user message and drives
the orchestrator: steering an active run (mid-run queue) or starting
a fresh turn (idle → dispatch). The persisted user message is fetched
back by its ``client_msg_id`` and returned so the client can render
the bubble immediately.

A delivery status of ``"locked"`` (another run holds the orchestrator
lock) surfaces as a 409 ``session_locked``; ``"busy"`` (the mid-run
queue rejected the enqueue) surfaces as a 409 ``session_busy``. In
both cases the message may still have been persisted, but the
orchestrator did not accept it for a turn, so the client should retry.

## Path parameters

- `session_id` string, required

## Request body

- ChatMessageCreate: Request body for ``POST /api/v1/chat/sessions/{id}/messages``. REST-only: the message is enqueued for the next agent turn and the response returns the persisted user message (no streaming).
  - `role` string
  - `content` string, required
  - `file_ids` string[], nullable
  - `workflow_id` string, nullable

## Response `201`

Successful Response

- ChatMessageOut: A chat message as returned by ``GET /api/v1/chat/sessions/{id}/messages``.
  - `id` string, required
  - `session_id` string, required
  - `role` string, required
  - `content` string, nullable
  - `tool_name` string, nullable
  - `tool_input` string, nullable
  - `tool_result` string, nullable
  - `tokens` integer
  - `seq` integer
  - `kind` string
  - `metadata` string, nullable
  - `sender_user_id` string, nullable
  - `sender_name` string, nullable
  - `created_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

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