data.chat.messages.list

Paginated list of chat messages for a conversation

List ChatMessage rows for a single ChatConversation.

Inputs:

• organization_uuid: Organization UUID (required).
• user_uuid: User UUID (required); must be a member of the organization.
• conversation_uuid: ChatConversation UUID (required).
• after_message_uuid: optional message UUID for forward / "load newer" scroll.
• before_message_uuid: optional message UUID for backward / "load older" scroll.
• limit: page size (optional, default 50, min 1, max 200).

Outputs (terminal state_data):

• messages: list ordered oldest-first. Each item: {message_uuid, conversation_uuid, role (str), content (str), metadata (dict), created_at (iso8601), parent_message_uuid (uuid|null)} metadata is slimmed to a UI-relevant allowlist (see _METADATA_KEEP_KEYS): the persisted blob is unbounded (DGI stamps working_set + reasoning internals on every assistant message), so echoing it verbatim tripped the engine's MAX_OUTPUT_ITEMS cap on a normal page.
• has_more_before: True when older messages exist than the lowest returned id.
• has_more_after: True when newer messages exist than the highest returned id.
• error: str | None (only on the ReadOnlyDataWorkflow soft-error path)

Failure modes (raised as WorkflowBusinessError with stable codes):

• organization_not_found_or_unauthorized — user not a member, or org/user uuid does not resolve
• conversation_not_found — uuid does not match any row in the caller's org

Overview

Property	Value
Workflow type	Atomic
Library	App-chat
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization UUID
user_uuid	uuid	No	—	User UUID — must belong to organization
conversation_uuid	uuid	Yes	—	ChatConversation UUID
after_message_uuid	uuid	No	—	Forward-scroll cursor — return messages created after this message uuid
before_message_uuid	uuid	No	—	Backward-scroll cursor — return messages created before this message uuid
limit	integer	No	50	Page size (1..200, default 50)

Output Schema

Field	Type	Required	Default	Description
messages	list	Yes	—	Message public dicts, ordered oldest-first within the page
has_more_before	boolean	Yes	—	True when older messages exist before the returned page
has_more_after	boolean	Yes	—	True when newer messages exist after the returned page
error	string	No	—	Error message when query failed
error_type	string	No	—	Error class name when query failed

States

State	Initial	Terminal	Success	Auto-advance	Description
done	Yes	Yes	Yes	—	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "data.chat.messages.list",
  "initial_data": {
    "organization_uuid": "value",
    "conversation_uuid": "value"
  }
}