---
title: "Handle New Chat Message"
method: POST
path: "/chat/send-message"
tags: ["public"]
---

# Handle New Chat Message

`POST /chat/send-message`

This endpoint is both used for all the following purposes:
- Sending a new message in the session
- Regenerating a message in the session (just send the same one again)
- Editing a message (similar to regenerating but sending a different message)
- Kicking off a seeded chat session (set `use_existing_user_message`)

Assumes that previous messages have been set as the latest to minimize overhead.

Args:
    chat_message_req (CreateChatMessageRequest): Details about the new chat message.
    request (Request): The current HTTP request context.
    user (User | None): The current user, obtained via dependency injection.
    _ (None): Rate limit check is run if user/group/global rate limits are enabled.

Returns:
    StreamingResponse: Streams the response to the new chat message.

## Request body

- CreateChatMessageRequest — Before creating messages, be sure to create a chat_session and get an id
  - `chunks_above` integer, nullable
  - `chunks_below` integer, nullable
  - `full_doc` boolean
  - `chat_session_id` string, uuid, required
  - `parent_message_id` integer, nullable, required
  - `message` string, required
  - `file_descriptors` FileDescriptor[]
    - `id` string, required
    - `type` 'image' | 'document' | 'plain_text' | 'csv', required
    - `name` string, nullable
    - `user_file_id` string, nullable
  - `search_doc_ids` integer[], nullable, required
  - `retrieval_options` RetrievalDetails, required
    - `chunks_above` integer, nullable
    - `chunks_below` integer, nullable
    - `full_doc` boolean
    - `run_search` 'always' | 'never' | 'auto'
    - `real_time` boolean
    - `filters` BaseFilters
      - `source_type` DocumentSource[], nullable
      - `document_set` string[], nullable
      - `time_cutoff` string, date-time, nullable
      - `tags` Tag[], nullable
        - `tag_key` string, required
        - `tag_value` string, required
    - `enable_auto_detect_filters` boolean, nullable
    - `offset` integer, nullable
    - `limit` integer, nullable
    - `dedupe_docs` boolean
  - `rerank_settings` RerankingDetails
    - `rerank_model_name` string, nullable, required
    - `rerank_api_url` string, nullable, required
    - `rerank_provider_type` 'cohere' | 'litellm' | 'bedrock', required
    - `rerank_api_key` string, nullable
    - `num_rerank` integer, required
    - `disable_rerank_for_streaming` boolean
  - `query_override` string, nullable
  - `regenerate` boolean, nullable
  - `llm_override` LLMOverride
    - `model_provider` string, nullable
    - `model_version` string, nullable
    - `temperature` number, nullable
  - `prompt_override` PromptOverride
    - `system_prompt` string, nullable
    - `task_prompt` string, nullable
  - `temperature_override` number, nullable
  - `alternate_assistant_id` integer, nullable
  - `persona_override_config` PersonaOverrideConfig
    - `name` string, required
    - `description` string, required
    - `search_type` 'keyword' | 'semantic' | 'internet'
    - `num_chunks` number, nullable
    - `llm_relevance_filter` boolean
    - `llm_filter_extraction` boolean
    - `recency_bias` 'favor_recent' | 'base_decay' | 'no_decay' | 'auto'
    - `llm_model_provider_override` string, nullable
    - `llm_model_version_override` string, nullable
    - `prompts` PromptOverrideConfig[]
      - `name` string, required
      - `description` string
      - `system_prompt` string, required
      - `task_prompt` string
      - `datetime_aware` boolean
      - `include_citations` boolean
    - `document_set_ids` integer[]
    - `tools` ToolConfig[]
      - `id` integer, required
    - `tool_ids` integer[]
    - `custom_tools_openapi` object[]
  - `use_existing_user_message` boolean
  - `existing_assistant_message_id` integer, nullable
  - `structured_response_format` object, nullable
  - `skip_gen_ai_answer_generation` boolean
  - `allowed_tool_ids` integer[], nullable
  - `forced_tool_ids` integer[], nullable
  - `deep_research` boolean

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

- **2026-01-06** `2d941ea53eb3` — 9 breaking, 13 warning, 22 info
  - request property `persona_override_config/anyOf[subschema #1: PersonaOverrideConfig]/recency_bias` was restricted to a list of enum values
  - request property `persona_override_config/anyOf[subschema #1: PersonaOverrideConfig]/search_type` was restricted to a list of enum values
  - request property `retrieval_options/anyOf[subschema #1: RetrievalDetails]/run_search` was restricted to a list of enum values
  - the request property `file_descriptors/items/id` became required
  - …40 more
- **2025-09-10** `624199972123` — 1 warning, 3 info
  - removed the request property `prompt_id`
  - added the new optional `query` request parameter `tenant_id`
  - added the new optional request property `allowed_tool_ids`
  - added the new optional request property `forced_tool_ids`
- **2025-08-21** `9321c45d93b5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/onyx-dot-app/apis/onyx-api/changes/chat/send-message/post.md)

---

[API](https://skmtc.dev/onyx-dot-app/apis/onyx-api.md) · [All operations](https://skmtc.dev/onyx-dot-app/apis/onyx-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/onyx-dot-app/onyx-api/revisions/2d941ea53eb3/schema)