Skip to main content

Workspace.Chats.Messages

Tags: chat, communication, messaging

Endpoints​

Messages​

GET /api/v2/w/{workspace_uuid}/chats/{chat_id}/messages

Description:

Chat message operations

Get messages from a specific chat with pagination.

Retrieves the message history for a chat in OpenAI-compatible format. Messages include content, role (user/assistant/system), tool calls, and metadata. Results are paginated for efficient loading of long conversations.

Path Parameters:

  • id: Chat ID to retrieve messages from

Query Parameters:

  • limit: Maximum number of messages to return (1-100, default: 10)
  • offset: Number of messages to skip for pagination (default: 0)

Response: Returns an array of OpenAIMessageResponse objects in reverse chronological order (most recent first), each containing message content, role, timestamps, and tool call data.

Permissions: Self-access: Users can view messages in their own chats. Admin access: CHATS_READ scope required to view other members' chat messages.

Error Responses:

  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: User does not have permission to view this chat
  • 404 Not Found: Chat not found

Related Endpoints:

  • GET /chats/{chat_id} - Get chat details
  • GET /chats/{chat_id}/tool-calls/{call_id}/messages - Get tool call messages
  • POST /chats/{chat_id}/send-assistant-message - Send a message as assistant

Authentication: Requires workspace member

Parameters:

  • chat_id (int | str)
  • limit (Integer)
  • offset (Integer)

Response: List of OpenAIMessageResponse

Messages​

GET /api/v2/w/{workspace_uuid}/chats/{chat_id}/messages

Description:

Chat message operations

Get paginated messages for a specific chat.

Retrieves chat messages with full pagination support including total count calculation. Messages are returned in OpenAI-compatible format with role, content, and tool call information.

Path Parameters:

  • chat_id: Chat ID to retrieve messages from

Query Parameters:

  • limit: Maximum messages per page (1-100, default: 10)
  • offset: Number of messages to skip (default: 0)
  • total_count: Whether to calculate total message count (default: false for performance)

Response: Returns a paginated response with message array, total count, page number, page size, and total pages. Messages are in OpenAI format with full metadata.

Permissions: Self-access: Users can view messages in their own chats. Admin access: CHATS_READ scope required to view other members' chat messages.

Error Responses:

  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: User does not have permission to view this chat
  • 404 Not Found: Chat not found

Related Endpoints:

  • GET /chats/{chat_id}/messages - Alternative messages endpoint
  • GET /chats/{chat_id} - Get chat details

Authentication: Requires workspace member

Parameters:

  • workspace_uuid (String)
  • chat_id (int | str)
  • limit (Integer)
  • offset (Integer)
  • total_count (Boolean)

Response: See PaginatedResponse[OpenAIMessageResponse]

Messages​

POST /api/v2/w/{workspace_uuid}/chats/{chat_id}/messages

Description:

Chat message operations

Send a user message in a chat.

For DM chats with human recipients, triggers SendDmNotificationWorkflow. Agent DM responses are handled via the AGUI streaming endpoint.

Authorization: Requires chats:write scope

Parameters:

Response: See OpenAIMessageResponse

Rate​

POST /api/v2/w/{workspace_uuid}/chats/{chat_id}/messages/{message_uuid}/rate

Description:

Chat message operations

Rate an assistant message for quality feedback.

Records user feedback on assistant message quality to Langfuse for observability and continuous improvement. Only assistant messages can be rated. Ratings are associated with the message's trace and observation IDs for detailed analysis.

Path Parameters:

  • chat_id: Chat ID containing the message
  • message_uuid: UUID of the message to rate

Request Body:

  • rating: Numeric rating value (e.g., 1.0 for positive, 0.0 for negative)
  • comment: Optional text comment explaining the rating

Response: Returns a success status confirming the rating was recorded in Langfuse.

Permissions: Self-access: Users can rate messages in their own chats. Admin access: CHATS_WRITE scope required to rate other members' chat messages.

Error Responses:

  • 400 Bad Request: Message is not an assistant message or integrity check failed
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: User does not have permission to rate messages in this chat
  • 404 Not Found: Chat or message not found
  • 500 Internal Server Error: Failed to record rating in Langfuse

Related Endpoints:

  • GET /chats/{chat_id}/messages - Get chat messages to rate
  • POST /chats/{chat_id}/send-assistant-message - Send assistant messages

Authentication: Requires workspace member

Parameters:

  • chat_id (int | str)
  • message_uuid (String)
  • rating_data (RateMessageRequest)

Messages​

GET /api/v2/w/{workspace_uuid}/chats/{chat_id}/tool-calls/{call_id}/messages

Description:

Chat message operations

Get messages from a specific tool call execution.

Retrieves the detailed message history from a tool call's ReACT loop execution. This includes sub-agent messages, tool invocations, and results from custom tools that run their own conversation loops.

Path Parameters:

  • id: Chat ID containing the tool call
  • call_id: Tool call ID to retrieve messages from

Query Parameters:

  • limit: Maximum number of messages to return (1-1000, default: 100)
  • offset: Number of messages to skip for pagination (default: 0)

Response: Returns an array of OpenAIMessageResponse objects representing the internal conversation flow within the tool execution, useful for debugging and transparency.

Permissions: Self-access: Users can view tool call messages in their own chats. Admin access: CHATS_READ scope required to view other members' chat messages.

Error Responses:

  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: User does not have permission to view this chat
  • 404 Not Found: Chat or tool call not found

Related Endpoints:

  • GET /chats/{chat_id}/messages - Get main chat messages
  • GET /chats/{chat_id}/tools - Get available tools for chat

Authentication: Requires workspace member

Parameters:

  • chat_id (int | str)
  • call_id (String)
  • limit (Integer)
  • offset (Integer)

Response: List of OpenAIMessageResponse