Messages API - LibreChat

The Messages API allows you to create, retrieve, update, and delete messages within conversations, as well as perform advanced operations like branching messages and editing artifacts.

Authentication

All endpoints require JWT authentication via the Authorization header:

Authorization: Bearer <your_jwt_token>

List Messages

curl -X GET "https://your-domain.com/api/messages?conversationId=<conversation_id>&pageSize=25" \
  -H "Authorization: Bearer <token>"

Retrieve messages with support for pagination, filtering by conversation, or full-text search.

Query Parameters

conversationId

string

Filter messages by conversation ID

messageId

string

Retrieve a specific message (requires conversationId)

string

Full-text search query (uses MeiliSearch)

cursor

string

Pagination cursor for next page

sortBy

string

default:"createdAt"

Sort field: endpoint, createdAt, or updatedAt

sortDirection

string

default:"desc"

Sort direction: asc or desc

pageSize

integer

default:"25"

Number of messages per page

Response

messages

array

Array of message objects

Show Message object

messageId

string

Unique message identifier

conversationId

string

Parent conversation ID

parentMessageId

string

ID of the previous message in the thread

text

string

Message text content (legacy field)

content

array

Structured content array (text, images, tool calls, etc.)

isCreatedByUser

boolean

Whether the message was created by the user

sender

string

Message sender (user name or AI model)

endpoint

string

Endpoint used (e.g., “openAI”, “anthropic”, “agents”)

model

string

Model name

createdAt

string

ISO 8601 timestamp

updatedAt

string

ISO 8601 timestamp

nextCursor

string | null

Cursor for next page, null if no more results

Get Messages by Conversation

curl -X GET "https://your-domain.com/api/messages/<conversation_id>" \
  -H "Authorization: Bearer <token>"

Retrieve all messages in a specific conversation.

Path Parameters

conversationId

string

required

The conversation ID

Response

Returns an array of message objects (excludes internal MongoDB fields _id, __v, user).

Get Specific Message

curl -X GET "https://your-domain.com/api/messages/<conversation_id>/<message_id>" \
  -H "Authorization: Bearer <token>"

Retrieve a specific message by conversation and message ID.

Path Parameters

conversationId

string

required

The conversation ID

messageId

string

required

The message ID

Response

Returns the message object or 404 Not Found if the message doesn’t exist.

Create Message

curl -X POST "https://your-domain.com/api/messages/<conversation_id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "<message_id>",
    "parentMessageId": "<parent_message_id>",
    "text": "Hello, world!",
    "content": [{"type": "text", "text": "Hello, world!"}],
    "isCreatedByUser": true,
    "sender": "User"
  }'

Create a new message in a conversation.

Path Parameters

conversationId

string

required

The conversation ID

Request Body

messageId

string

required

Unique message identifier (UUID)

parentMessageId

string

ID of the previous message in the thread

text

string

Message text content (legacy)

content

array

Structured content array with parts like text, images, or tool calls

isCreatedByUser

boolean

required

Whether this is a user message

sender

string

required

Sender name (e.g., “User” or model name)

endpoint

string

Endpoint identifier

model

string

Model name

Response

Returns the saved message object.

Error Responses

400 Bad Request: Message not saved
500 Internal Server Error: Save failed

Update Message Text

curl -X PUT "https://your-domain.com/api/messages/<conversation_id>/<message_id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Updated message text",
    "model": "gpt-4"
  }'

Update the text content of a message. Supports updating either the entire message text or a specific content part by index.

Path Parameters

conversationId

string

required

The conversation ID

messageId

string

required

The message ID

Request Body

text

string

required

New text content

model

string

Model name (for token counting)

index

integer

Content part index to update (optional, updates entire message if omitted)

Response

Returns the updated message object.

Error Responses

400 Bad Request: Invalid index or attempting to update non-text content
404 Not Found: Message not found
500 Internal Server Error: Update failed

Update Message Feedback

curl -X PUT "https://your-domain.com/api/messages/<conversation_id>/<message_id>/feedback" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback": {
      "rating": 1,
      "comment": "Great response!"
    }
  }'

Add or update feedback on a message.

Path Parameters

conversationId

string

required

The conversation ID

messageId

string

required

The message ID

Request Body

feedback

object

Feedback object (set to null to clear feedback)

Show Feedback object

feedback.rating

integer

Rating value (e.g., 1 for positive, -1 for negative)

feedback.comment

string

Optional feedback comment

Response

messageId

string

The message ID

conversationId

string

The conversation ID

feedback

object | null

Updated feedback object

Delete Message

curl -X DELETE "https://your-domain.com/api/messages/<conversation_id>/<message_id>" \
  -H "Authorization: Bearer <token>"

Delete a specific message.

Path Parameters

conversationId

string

required

The conversation ID

messageId

string

required

The message ID

Response

Returns 204 No Content on success.

Branch Message (Parallel Agents)

curl -X POST "https://your-domain.com/api/messages/branch" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "<message_id>",
    "agentId": "<agent_id>"
  }'

Create a new branch message from a specific agent’s content in a parallel response message. Only works with non-user messages that have content attributions.

Request Body

messageId

string

required

Source message ID

agentId

string

required

Agent ID to filter content by

Response

Returns the newly created branch message with content filtered to only include parts from the specified agent.

Error Responses

400 Bad Request: Missing parameters, attempting to branch from user message, or no content found for agent
404 Not Found: Source message not found
500 Internal Server Error: Branch creation failed

Edit Artifact

curl -X POST "https://your-domain.com/api/messages/artifact/<message_id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "index": 0,
    "original": "original artifact content",
    "updated": "updated artifact content"
  }'

Edit artifact content within a message (e.g., code blocks, formatted content).

Path Parameters

messageId

string

required

The message ID containing the artifact

Request Body

index

integer

required

Artifact index (0-based)

original

string

required

Original artifact content to replace

updated

string

required

New artifact content

Response

conversationId

string

The conversation ID

content

array

Updated message content array

text

string

Updated message text

Error Responses

400 Bad Request: Invalid parameters or artifact not found
404 Not Found: Message not found
500 Internal Server Error: Update failed

Common Error Codes

Status Code	Description
400	Bad Request - Invalid parameters or unsupported operation
401	Unauthorized - Invalid or missing JWT token
403	Forbidden - User lacks permission to access the conversation
404	Not Found - Message or conversation does not exist
500	Internal Server Error - Server-side error occurred

Overview

Endpoints

​Authentication

​List Messages

​Query Parameters

​Response

​Get Messages by Conversation

​Path Parameters

​Response

​Get Specific Message

​Path Parameters

​Response

​Create Message

​Path Parameters

​Request Body

​Response

​Error Responses

​Update Message Text

​Path Parameters

​Request Body

​Response

​Error Responses

​Update Message Feedback

​Path Parameters

​Request Body

​Response

​Delete Message

​Path Parameters

​Response

​Branch Message (Parallel Agents)

​Request Body

​Response

​Error Responses

​Edit Artifact

​Path Parameters

​Request Body

​Response

​Error Responses

​Common Error Codes

Build docs developers (and LLMs) love

Authentication

List Messages

Query Parameters

Response

Get Messages by Conversation

Path Parameters

Response

Get Specific Message

Path Parameters

Response

Create Message

Path Parameters

Request Body

Response

Error Responses

Update Message Text

Path Parameters

Request Body

Response

Error Responses

Update Message Feedback

Path Parameters

Request Body

Response

Delete Message

Path Parameters

Response

Branch Message (Parallel Agents)

Request Body

Response

Error Responses

Edit Artifact

Path Parameters

Request Body

Response

Error Responses

Common Error Codes