chat.conversation.create

Create a new chat conversation owned by a member or an app end-user

Create a new chat conversation for a (organization, user) pair.

Inputs:

• organization_uuid: UUID of the organization (required)
• user_uuid: UUID of the user opening the chat (required, must be a member)
• title: optional thread title (default "New conversation")
• seed_system_message: optional system-role first message
• metadata: free-form dict persisted on the conversation row

Outputs (terminal state_data):

• conversation_uuid: ChatConversation.uuid
• created_at: ISO-8601 timestamp
• title: resolved title

Failure reasons:

• organization_not_found_or_unauthorized
• validation_failed
• database_error

Overview

Property	Value
Workflow type	Atomic
Library	App-chat
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	UUID of the organization that owns the conversation
user_uuid	uuid	No	—	UUID of the MEMBER opening the chat (must be a member of the org). Required for a member run; refused on an end-user run, where the owner is the server-resolved principal from the verified token
title	string	No	—	Conversation title (default 'New conversation', max 200 chars)
seed_system_message	string	No	—	Optional system-role seed message (max 8000 chars)
metadata	json	No	—	Free-form metadata persisted on the conversation row (default empty)

Output Schema

Field	Type	Required	Default	Description
conversation_uuid	uuid	Yes	—	Created ChatConversation.uuid (external identifier)
created_at	string	Yes	—	ISO-8601 creation timestamp of the conversation
title	string	Yes	—	Resolved conversation title
failure_reason	string	No	—	Controlled-vocabulary failure key OR raw engine message
error	string	No	—	Human-readable error detail (echoed by action_fail)
error_type	string	No	—	Exception class name (engine-stamped)
failed_at_state	string	No	—	State name where the failure occurred (engine-stamped)
failed_step	string	No	—	DAG step name where the failure occurred (engine-stamped)
failed_layer	string	No	—	DAG layer where the failure occurred (engine-stamped)
organization_uuid	uuid	No	—	Organization UUID echoed by action_fail
user_uuid	uuid	No	—	User UUID echoed by action_fail

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

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

{
  "workflow_type": "chat.conversation.create",
  "initial_data": {
    "organization_uuid": "value"
  }
}