Sign in
Threads

Add Message to Thread with Optional Attachments

Add a user message to an existing thread with optional file attachments. Accepts both JSON (application/json) and form-data (multipart/form-data) payloads. Use JSON for text-only messages; use form-data when uploading file attachments. Can send text only, attachments only, or both. Documents must be indexed before further messages are allowed. To choose a model, set llm_provider and model_name. If omitted, defaults are llm_provider=openai and model_name=gpt-4o. When stream=true, the SSE feed emits content_streaming answer deltas and may also emit reasoning_streaming events when the selected provider exposes native live reasoning deltas; those events are live-only and are not persisted. Set thinking to a flat object such as {"effort": "high"} or {"budget_tokens": 8192} to request reasoning on supported models/providers. Use {} to enable provider defaults. Memory defaults to 'off'. Set memory='Auto' for workspace-scoped memory search and automatic memory operations, or memory='Readonly' for search-only. Supported attachment types: .pdf, .doc(x), .ppt(x), .xls(x), .txt, .csv, .md, .json(l), .xml, .py, .js, .ts, .jsx, .tsx, .html, .css, .cpp, .c, .h, .java, .go, .rs, .rb, .php, .sql, .png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff, .tif, .mp3, .wav, .m4a, .ogg, .flac, .aac (audio), .mp4, .mov, .avi, .mkv, .mpeg, .mpg, .webm (video). Audio/video files are sent inline to models that natively accept them. See the Model Library page in the dashboard (model-library page) for a current list of supported models and providers.

post/threads/{thread_id}/messages

Path parameters

thread_idstring uuid required

Headers

authorizationstring nullable
x_session_tokenstring nullable

Request body

contentstring

Text content of the message

llm_providerstring nullable

LLM provider name. Default: openai.

model_namestring nullable

Model name. Default: gpt-4o.

system_promptstring nullable

Per-run system prompt override. Not persisted on the assistant.

image_generation'auto' | 'off'

Image generation: 'auto' enables the generate_image tool (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). Ignored when image_generation=off.

image_model_namestring nullable

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

streamboolean

Whether to stream the AI response.

toolsobject[] nullable

Optional per-message tool override (OpenAI-style). Not persisted on the assistant.

memorystring

Memory Lite mode (no reranking): 'Auto', 'Readonly', or 'off' (default). Cannot be used together with memory_pro.

memory_response_citationboolean

Whether the assistant should cite retrieved memories in its response text.

memory_citationboolean

Deprecated alias for memory_response_citation.

memory_prostring nullable

Memory Pro mode (with reranking, higher cost): 'Auto', 'Readonly', or omit. Cannot be used together with memory.

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. Ignored when RAG, web search, or custom tools are active.

custom_timestampstring date-time nullable

Custom timestamp for the message (merged into metadata when stored).

metadatastring

Optional metadata as JSON string.

voiceobject

Optional voice config object. Add stt to enable speech-to-text, add tts to enable text-to-speech.

Example request

{
  "thinking": {},
  "openrouter": {
    "sort": "price"
  }
}

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