data.chat.conversations.list

Paginated list of chat conversations for a (org, user) pair

List ChatConversation rows owned by a (organization, user) pair.

Inputs:

• organization_uuid: Organization UUID (required).
• user_uuid: User UUID (required); conversations are scoped to this user as owner.
• cursor: Opaque pagination token from a previous page (optional).
• limit: Page size (optional, default 20, min 1, max 100).
• include_archived: When True include archived threads (default False).

Outputs (terminal state_data):

• conversations: list of dicts ordered by updated_at DESC. Each item: {conversation_uuid, title, created_at (iso), updated_at (iso), last_message_preview (str|null), message_count (int), archived (bool)}
• next_cursor: opaque cursor for the next page, or null when exhausted
• total_estimate: approximate count for the (org, user, archived) slice; capped at 10,000 to keep the response cheap
• error: str | None (only on the ReadOnlyDataWorkflow soft-error path)

Failure modes (raised as WorkflowBusinessError with stable codes):

• organization_not_found_or_unauthorized — user is not a member of the org
• invalid_cursor — cursor cannot be decoded

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 (string form)
user_uuid	uuid	No	—	User UUID (string form) — conversations scoped to this user
cursor	string	No	—	Opaque pagination cursor from a previous page
limit	integer	No	20	Page size (1..100, default 20)
include_archived	boolean	No	False	When True, include archived conversations

Output Schema

Field	Type	Required	Default	Description
conversations	list	Yes	—	Conversation public dicts, ordered by updated_at DESC
next_cursor	string	No	—	Cursor for the next page, or null when exhausted
total_estimate	integer	Yes	—	Approximate total rows in the (org,user,archived) slice
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.conversations.list",
  "initial_data": {
    "organization_uuid": "value"
  }
}