Sign in

v1

latestOpenAPI 3.1.0raw.githubusercontent.com2026-06-25173140700.7 KB
Message

Create a message

Send a JSON message to a chat (or start a new one) and enqueue generation.

post/messages/

Query parameters

cookie_namestring nullable

Request body

contentstring nullable

Text content of the user message.

chat_idinteger nullable

ID of an existing chat to post into; omit to start a new chat.

updated_atstring date-time nullable

Last-known chat timestamp, used for optimistic concurrency.

project_idinteger nullable

ID of the project to associate a new chat with.

modelstring nullable

Name of the LLM model to use for a new chat.

temperaturenumber nullable

Sampling temperature for a new chat.

similarity_top_kinteger nullable

Number of top similar chunks to retrieve for a new chat.

system_promptstring nullable

System prompt for a new chat.

assistant_idinteger nullable

ID of an assistant to drive a new chat.

privateboolean nullable

Whether a new chat is private to its creator.

form_dataobject nullable

Form submission data, accepted only when starting a new chat with a form-input assistant.

Example request

{
  "content": "Summarize the attached report.",
  "chat_id": 42,
  "updated_at": "2026-01-15T10:30:00Z",
  "project_id": 7,
  "model": "gpt-4o",
  "temperature": 0.7,
  "similarity_top_k": 5,
  "system_prompt": "You are a concise analyst.",
  "assistant_id": 3,
  "form_data": {
    "topic": "Q3 results"
  }
}

Response

Successful Response

statestring nullable

Current lifecycle state of the record.

state_reasonstring nullable

Optional explanation for the current state.

state_changed_atstring date-time nullable

UTC timestamp when the state last changed.

idinteger nullable

Primary key for the message.

created_atstring date-time

Timestamp when the message was created.

updated_atstring date-time

Timestamp when the message was last updated.

creator_user_idinteger required

ID of the user who created the message.

chat_idinteger required

ID of the chat the message belongs to.

rolestring required

Role of the message author (see llama-index MessageRole values).

contentstring required

Rendered content of the message.

sent_user_msgstring nullable required

Original user-sent message text, if applicable.

parent_idinteger nullable required

ID of the parent message in a threaded conversation.

completedboolean

DEPRECATED. Whether the message has finished processing.

errorstring nullable required

DEPRECATED. Error message captured during processing, if any.

hintstring nullable required

Hint shown to the user about the next action.

llm_catalog_idinteger nullable

ID of the LLM catalog entry used for this message.

llm_settings_idinteger nullable

ID of the LLM settings used for this message.

usageobject nullable

Token usage metadata recorded for this message.

celery_task_idstring nullable

ID of the Celery task processing this message, if any.

Example response

{
  "state": "NEW",
  "state_reason": "Processing failed: timeout",
  "state_changed_at": "2026-01-16T08:00:00Z",
  "id": 1,
  "created_at": "2026-06-23T12:00:00Z",
  "updated_at": "2026-06-23T12:00:00Z",
  "creator_user_id": 1,
  "chat_id": 1,
  "role": "user",
  "content": "Hello, how can I help you?",
  "sent_user_msg": "Summarize the attached document.",
  "parent_id": 1,
  "completed": true,
  "error": "Model timed out",
  "hint": "You can ask a follow-up question.",
  "llm_catalog_id": 1,
  "llm_settings_id": 1,
  "usage": {
    "completion_tokens": 120,
    "prompt_tokens": 50
  },
  "celery_task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}