Overview
The Messages API allows you to create, retrieve, update, and delete messages within conversations. Messages are the core content of conversations and can include text, images, and other content types.
All message endpoints are prefixed with /api/messages.
List Messages
Retrieve messages with pagination and filtering:
GET /api/messages
Authorization: Bearer <token>
Query Parameters
Filter by conversation ID
Get specific message by ID
Search messages by content (uses MeiliSearch)
Number of results per page
sortBy
string
default:"createdAt"
Sort field: endpoint, createdAt, or updatedAt
Sort direction: asc or desc
Response
Cursor for next page (null if no more pages)
{
"messages": [
{
"messageId": "msg123",
"conversationId": "conv456",
"parentMessageId": "msg122",
"text": "What are the best practices for machine learning?",
"content": [
{
"type": "text",
"text": "What are the best practices for machine learning?"
}
],
"sender": "User",
"isCreatedByUser": true,
"createdAt": "2024-01-15T10:00:00Z",
"endpoint": "openAI",
"model": "gpt-4"
}
],
"nextCursor": "cursor_abc"
}
Get Messages by Conversation
Retrieve all messages in a specific conversation:
GET /api/messages/:conversationId
Authorization: Bearer <token>
Path Parameters
Response
Returns an array of messages ordered by creation time.
[
{
"messageId": "msg123",
"conversationId": "conv456",
"text": "Hello!",
"isCreatedByUser": true,
"createdAt": "2024-01-15T10:00:00Z"
},
{
"messageId": "msg124",
"parentMessageId": "msg123",
"conversationId": "conv456",
"text": "Hi! How can I help you today?",
"isCreatedByUser": false,
"sender": "Assistant",
"createdAt": "2024-01-15T10:00:01Z"
}
]
Get Single Message
Retrieve a specific message:
GET /api/messages/:conversationId/:messageId
Authorization: Bearer <token>
Path Parameters
Response
Unique message identifier
ID of the previous message in the conversation thread
Message text content (legacy field)
Array of content parts (text, images, artifacts, etc.)
Sender name or identifier
Whether the message was created by the user (vs AI)
Number of tokens in the message
Whether the message generation was interrupted
Whether an error occurred during generation
Create Message
Create a new message in a conversation:
POST /api/messages/:conversationId
Authorization: Bearer <token>
Content-Type: application/json
{
"messageId": "msg125",
"parentMessageId": "msg124",
"text": "Tell me more about neural networks",
"isCreatedByUser": true,
"sender": "User"
}
Path Parameters
Request Body
Unique message identifier (UUID)
Whether this is a user message
Response
Returns the created message object with HTTP status 201.
Update Message
Update an existing message’s text content:
PUT /api/messages/:conversationId/:messageId
Authorization: Bearer <token>
Content-Type: application/json
{
"text": "Updated message text",
"model": "gpt-4"
}
Path Parameters
Request Body
Model used (for token counting)
Index of content part to update (for multi-part content)
Response
Returns the updated message object.
Update Content Part
To update a specific content part by index:
{
"text": "Updated content part",
"index": 0,
"model": "gpt-4"
}
text and think content types can be updated.
Update Message Feedback
Add or update feedback (thumbs up/down) for a message:
PUT /api/messages/:conversationId/:messageId/feedback
Authorization: Bearer <token>
Content-Type: application/json
{
"feedback": {
"rating": "thumbsUp",
"comment": "Very helpful response!"
}
}
Request Body
Feedback object (or null to remove feedback)
Rating: thumbsUp or thumbsDown
Optional feedback comment
Response
{
"messageId": "msg124",
"conversationId": "conv456",
"feedback": {
"rating": "thumbsUp",
"comment": "Very helpful response!"
}
}
Delete Message
Delete a specific message:
DELETE /api/messages/:conversationId/:messageId
Authorization: Bearer <token>
Path Parameters
Response
HTTP 204 No Content on success.
Branch Message
Create a new message branch from parallel agent responses:
POST /api/messages/branch
Authorization: Bearer <token>
Content-Type: application/json
{
"messageId": "msg124",
"agentId": "agent_abc"
}
Request Body
Source message ID containing parallel responses
Agent ID to filter content by
Response
Creates a new message containing only the content from the specified agent.
{
"messageId": "msg125",
"parentMessageId": "msg123",
"conversationId": "conv456",
"content": [
{
"type": "text",
"text": "Content from agent_abc only"
}
],
"sender": "Agent ABC",
"isCreatedByUser": false
}
Update Artifact
Update code artifacts within a message:
POST /api/messages/artifact/:messageId
Authorization: Bearer <token>
Content-Type: application/json
{
"index": 0,
"original": "console.log('Hello')",
"updated": "console.log('Hello, World!')"
}
Path Parameters
Message ID containing the artifact
Request Body
Index of the artifact to update (0-based)
Original artifact content (for verification)
Response
{
"conversationId": "conv456",
"content": [...],
"text": "Updated message with modified artifact"
}
Message Content Types
Messages support multiple content types:
Text Content
{
"type": "text",
"text": "Message content"
}
Image Content
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.png"
}
}
Code Artifact
{
"type": "code",
"code": "console.log('Hello, World!');",
"language": "javascript"
}
Thinking Process
{
"type": "think",
"think": "Internal reasoning process..."
}
Message Attachments
Messages can include file attachments:
{
"attachments": [
{
"file_id": "file_abc123",
"filename": "document.pdf",
"type": "file",
"size": 102400,
"filepath": "/uploads/file_abc123.pdf"
}
]
}
Search Messages
Search across all messages (requires MeiliSearch):
GET /api/messages?search=machine%20learning
Authorization: Bearer <token>
Error Responses
Message Not Found
{
"error": "Message not found"
}
Invalid Content Update
{
"error": "Cannot update non-text content"
}
Cannot Branch User Message
{
"error": "Cannot branch from user messages"
}
TypeScript Types
import type { TMessage, TMessageContentParts } from 'librechat-data-provider';
interface TMessage {
messageId: string;
conversationId: string;
parentMessageId?: string;
text?: string;
content?: TMessageContentParts[];
sender: string;
isCreatedByUser: boolean;
endpoint?: string;
model?: string;
tokenCount?: number;
attachments?: TAttachment[];
createdAt?: string;
updatedAt?: string;
unfinished?: boolean;
error?: boolean;
feedback?: TMessageFeedback;
}