---
title: "Send Message (Stateless or Stateful)"
method: POST
path: "/threads/messages"
tags: ["Threads"]
---

# Send Message (Stateless or Stateful)

`POST /threads/messages`

Send a message without needing to create a thread or assistant first. Everything you pass is per-turn only — nothing is persisted to the assistant. To configure an assistant permanently, use the dedicated assistant endpoints.

**Without thread_id** → a new thread (and default assistant) are auto-created. The response includes thread_id and assistant_id.

**With thread_id** → the message is appended to the existing thread.

**With assistant_id** → the new thread is pinned to that assistant.

Accepts **application/json** (text-only and JSON-safe fields) or **multipart/form-data** for file attachments, `audio_file` (STT), and the same form fields as `POST /threads/{thread_id}/messages`. Image generation, voice (TTS/STT), and `tools` behave the same as the thread messages endpoint.

## Headers

- `authorization` string, nullable
- `x_session_token` string, nullable

## Request body

- object
  - `thread_id` string, uuid, nullable — Existing thread UUID. Omit to auto-create a new thread.
  - `assistant_id` string, uuid, nullable — Assistant UUID to use. Omit to auto-create a brand-new assistant for this turn; pass the returned assistant_id back to reuse it on later messages.
  - `content` string — Text content of the message.
  - `system_prompt` string, nullable — Instructions for this turn. Must be re-passed every call; not persisted. Falls back to the assistant's stored description if omitted.
  - `llm_provider` string, nullable — LLM provider name (e.g. openai, anthropic, google). Default: openai.
  - `model_name` string, nullable — Model name (e.g. gpt-4o, claude-sonnet-4-20250514). Default: gpt-4o.
  - `image_generation` 'auto' | 'off' — Image generation: 'auto' enables generate_image (requires image_model_provider and image_model_name); 'off' disables it.
  - `image_model_provider` string, nullable — Required when image_generation=auto. Provider for generate_image (e.g. openrouter).
  - `image_model_name` string, nullable — Required when image_generation=auto. Model for generate_image (e.g. google/gemini-2.5-flash-image).
  - `stream` boolean — Whether to stream the AI response via SSE.
  - `thinking` object, nullable — Flat reasoning controls inferred from the selected llm_provider/model. Use {} to enable provider defaults, or send only the fields supported by the selected model.
    - `effort` 'low' | 'medium' | 'high' | 'max' — Use for OpenAI, xAI, and Gemini 3 models.
    - `budget_tokens` integer — Use for Anthropic and Gemini 2.5 models.
    - `max_tokens` integer — Use for OpenRouter and Cerebras reasoning models.
    - `exclude_reasoning` boolean — Use for OpenRouter and Cerebras reasoning models.
  - `tools` object[], nullable — Tool definitions for this turn (OpenAI-style). Must be re-passed every call; not persisted.
  - `memory` string — Memory Lite mode: 'Auto', 'Readonly', or 'off' (default).
  - `memory_response_citation` boolean — Whether the assistant should cite retrieved memories.
  - `memory_citation` boolean — Deprecated alias for memory_response_citation.
  - `memory_pro` string, nullable — Memory Pro mode: 'Auto', 'Readonly', or omit.
  - `web_search` string — Web search mode: 'Auto' or 'off'.
  - `send_to_llm` string — Whether to send to LLM for a response.
  - `json_output` boolean — When true, request JSON object output from the model.
  - `custom_timestamp` string, date-time, nullable — Custom timestamp for the message (merged into metadata for storage).
  - `metadata` string — Optional metadata as JSON string or object.
  - `voice` object — Optional voice config. Add `stt` for speech-to-text (requires multipart + audio_file); add `tts` for text-to-speech.

## Response `200`

Successful Response

- MessageResponse — Response for message operations - includes content at top level for easy access
  - `message` string, required
  - `thread_id` string, uuid, required
  - `assistant_id` string, uuid, nullable
  - `content` string, nullable
  - `message_id` string, uuid, nullable
  - `role` 'user' | 'assistant' | 'tool'
  - `status` 'IN_PROGRESS' | 'REQUIRES_ACTION' | 'COMPLETED' | 'FAILED' | 'CANCELLED'
  - `tool_calls` object[], nullable
  - `run_id` string, nullable
  - `memory_operation_id` string, nullable
  - `retrieved_memories` RetrievedMemory[], nullable
    - `id` string, nullable
    - `memory` string, required
    - `score` number, nullable
  - `retrieved_files` string[], nullable
  - `retrieved_files_count` integer
  - `reasoning` string, nullable
  - `model_provider` string, nullable
  - `model_name` string, nullable
  - `input_tokens` integer, nullable
  - `output_tokens` integer, nullable
  - `total_tokens` integer, nullable
  - `created_at` string, date-time, nullable
  - `attachments` AttachmentInfo[], nullable
    - `document_id` string, uuid, required
    - `filename` string, required
    - `status` string, required
    - `file_size_bytes` integer, required
    - `summary` string, nullable
  - `generated_media` GeneratedMediaInfo[], nullable
    - `document_id` string, required
    - `media_type` string, required
    - `mime_type` string, required
    - `url` string, required
    - `file_size_bytes` integer, nullable
    - `transcript` string, nullable
  - `voice_records` VoiceRecord — Voice pipeline outcome for this turn: STT and/or TTS (artifacts + billing dimensions).
    - `stt` STTUsageInfo — STT result: transcript, input audio URL, billing dimensions, and raw provider output.
      - `provider` string, required
      - `model` string, required
      - `transcript` string, nullable
      - `audio_url` string, nullable — Presigned URL for the user's original audio input
      - `language` string, nullable
      - `duration_seconds` number, nullable
      - `input_tokens` integer, nullable
      - `output_tokens` integer, nullable
      - `audio_input_tokens` integer, nullable
      - `provider_output` object, nullable — Provider-specific response data (e.g. words, segments, entities, logprobs).
    - `tts` TTSUsageInfo — TTS result: synthesized audio URL, billing dimensions, and raw provider output.
      - `provider` string, required
      - `model` string, required
      - `audio_url` string, nullable — Presigned URL for synthesized speech output
      - `voice` string, nullable
      - `output_format` string, nullable
      - `characters` integer, nullable
      - `duration_seconds` number, nullable
      - `input_tokens` integer, nullable
      - `audio_output_tokens` integer, nullable
      - `provider_output` object, nullable — Provider-specific response data.
  - `timestamp` string, date-time, required
  - `context_usage` object, nullable

## Other responses

- `422` — Validation Error

---

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