data.chat.conversations.get

Fetch a single chat conversation by UUID for a (org, user) pair

Fetch a single chat conversation by UUID, scoped to a (organization, user) pair.

Inputs (ADR-015):

• organization_uuid: Organization UUID (required, string).
• user_uuid: User UUID (required, string). Must be a member of the organization or the call is rejected as unauthorized.
• conversation_uuid: Conversation UUID (required, string). Matched against ChatConversation.uuid within the same org.

Outputs (ADR-015 — terminal state_data on success):

• conversation_uuid: ChatConversation.uuid (str)
• title: Resolved title (str, possibly empty)
• created_at: ISO-8601 timestamp (str)
• updated_at: ISO-8601 timestamp (str | null when never updated)
• message_count: Denormalized counter (int)
• metadata: Pass-through of ChatConversation.metadata_json (dict)
• archived: Whether the thread is archived (bool)

Failure vocabulary (raised as WorkflowBusinessError with stable codes):

• organization_not_found_or_unauthorized — caller is not a member of the org (or the org/user UUID does not resolve). Returned BEFORE the row lookup so existence is never leaked to an unauthorized caller.
• conversation_not_found — caller is authorized but the conversation UUID does not exist in this org.
• validation_failed — engine-level input validation rejected the request.

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) — must be a member of the org
conversation_uuid	uuid	Yes	—	ChatConversation UUID (string form)

Output Schema

Field	Type	Required	Default	Description
conversation_uuid	uuid	Yes	—	ChatConversation UUID
title	string	Yes	—	Thread title (may be empty string)
created_at	string	Yes	—	ISO-8601 creation timestamp
updated_at	string	No	—	ISO-8601 last-update timestamp (null when never updated)
message_count	integer	Yes	—	Denormalized message counter
metadata	dict	Yes	—	Pass-through of ChatConversation.metadata_json
archived	boolean	Yes	—	Whether the conversation is archived
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.get",
  "initial_data": {
    "organization_uuid": "value",
    "conversation_uuid": "value"
  }
}