Messages API

API endpoints for managing messages within conversations

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

GET /api/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)

search · 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

GET /api/messages/:conversationId

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

GET /api/messages/:conversationId/:messageId

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

POST /api/messages/:conversationId

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

PUT /api/messages/:conversationId/:messageId

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

PUT /api/messages/:conversationId/:messageId/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

DELETE /api/messages/:conversationId/:messageId

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)

POST /api/messages/branch

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

POST /api/messages/artifact/:messageId

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