Messages

Endpoints for managing chat messages.

GET /api/chats/{id}/messages

List all messages in a chat conversation.

Authentication: Required (session)

Pre-blocks: chat.lookup

Response:

{
  "_links": {
    "self": { "href": "/api/chats/{id}/messages" }
  },
  "_embedded": {
    "inf:message": [
      {
        "id": "msg-123",
        "chatId": "chat-456",
        "role": "user",
        "content": "What were the Q4 sales figures?",
        "liked": null,
        "cost": 0,
        "memoryId": null,
        "createdAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "msg-124",
        "chatId": "chat-456",
        "role": "assistant",
        "content": "Based on the data, Q4 sales reached $2.5M...",
        "liked": true,
        "cost": 0.0042,
        "memoryId": "mem-789",
        "toolUses": [
          {
            "toolName": "dataset_query",
            "args": { "query": "SELECT SUM(sales)..." }
          }
        ],
        "createdAt": "2024-01-15T10:30:15Z"
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

Message Properties:

Field	Type	Description
id	string	Unique message ID
chatId	string	Parent chat ID
role	string	user or assistant
content	string	Message text content
liked	boolean	User feedback (true/false/null)
cost	number	Cost in USD for this message
memoryId	string	Associated memory ID
toolUses	array	Tools invoked during generation
createdAt	date	Message timestamp

---

DELETE /api/chats/{id}/messages

Clear all messages from a chat (preserves chat metadata and settings).

Authentication: Required (session)

Pre-blocks: chat.lookup

Response:

204 No Content

Data Loss

This operation permanently deletes all messages. Memories associated with deleted messages remain but lose their message references.

---

GET /api/messages/{id}

Retrieve a single message by ID.

Authentication: Required (session)

Pre-blocks: message.lookup

Response:

{
  "id": "msg-123",
  "chatId": "chat-456",
  "role": "assistant",
  "content": "Here's the analysis...",
  "liked": true,
  "cost": 0.0042,
  "memoryId": "mem-789",
  "toolUses": [],
  "createdAt": "2024-01-15T10:30:00Z"
}

---

PUT /api/messages/{id}

Update message properties (primarily for feedback).

Authentication: Required (session)

Pre-blocks: message.lookup

Request Body:

Field	Type	Description
liked	boolean	User feedback: true (liked), false (disliked), null (neutral)

Example Request:

{
  "liked": true
}

Response:

Returns the updated message object.

---

DELETE /api/messages/{id}

Delete a specific message and invalidate related cache entries.

Authentication: Required (session)

Pre-blocks: message.lookup

Response:

204 No Content

Side Effects:

• Removes message from chat history
• Invalidates prompt cache entries referencing this message
• Updates memory associations if applicable

Message Threading

Deleting a message in the middle of a conversation may affect context for subsequent AI responses. Consider clearing all messages instead of selective deletion.