Sign in
Threads

Send Message (Stateless or Stateful)

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.

post/threads/messages

Headers

authorizationstring nullable
x_session_tokenstring nullable

Request body

thread_idstring uuid nullable

Existing thread UUID. Omit to auto-create a new thread.

assistant_idstring 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.

contentstring

Text content of the message.

system_promptstring nullable

Instructions for this turn. Must be re-passed every call; not persisted. Falls back to the assistant's stored description if omitted.

llm_providerstring nullable

LLM provider name (e.g. openai, anthropic, google). Default: openai.

model_namestring 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_providerstring nullable

Required when image_generation=auto. Provider for generate_image (e.g. openrouter).

image_model_namestring nullable

Required when image_generation=auto. Model for generate_image (e.g. google/gemini-2.5-flash-image).

streamboolean

Whether to stream the AI response via SSE.

toolsobject[] nullable

Tool definitions for this turn (OpenAI-style). Must be re-passed every call; not persisted.

memorystring

Memory Lite mode: 'Auto', 'Readonly', or 'off' (default).

memory_response_citationboolean

Whether the assistant should cite retrieved memories.

memory_citationboolean

Deprecated alias for memory_response_citation.

memory_prostring nullable

Memory Pro mode: 'Auto', 'Readonly', or omit.

web_searchstring

Web search mode: 'Auto' or 'off'.

send_to_llmstring

Whether to send to LLM for a response.

json_outputboolean

When true, request JSON object output from the model.

custom_timestampstring date-time nullable

Custom timestamp for the message (merged into metadata for storage).

metadatastring

Optional metadata as JSON string or object.

voiceobject

Optional voice config. Add stt for speech-to-text (requires multipart + audio_file); add tts for text-to-speech.

Example request

{
  "thinking": {}
}

Response

Successful Response

messagestring required
thread_idstring uuid required
assistant_idstring uuid nullable
contentstring nullable
message_idstring uuid nullable
role'user' | 'assistant' | 'tool'
status'IN_PROGRESS' | 'REQUIRES_ACTION' | 'COMPLETED' | 'FAILED' | 'CANCELLED'
tool_callsobject[] nullable
run_idstring nullable
memory_operation_idstring nullable
retrieved_filesstring[] nullable
retrieved_files_countinteger
reasoningstring nullable
model_providerstring nullable
model_namestring nullable
input_tokensinteger nullable
output_tokensinteger nullable
total_tokensinteger nullable
created_atstring date-time nullable
timestampstring date-time required
context_usageobject nullable

Changes