Chats
Documentation for Chats
Base path: /api/v1/chats
Chat threads are the primary interaction surface for AI-powered workflow authoring and execution. Each thread contains a conversation history and is optionally linked to a workflow draft or a decision rule draft.
All endpoints require JWT authentication (Authorization: Bearer <token> or Cookie: token=<jwt>) and an x-active-org header.
Endpoints Overview
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/chats | Create a new empty chat thread |
| POST | /api/v1/chats/from-workflow | Create a thread linked to a workflow version |
| GET | /api/v1/chats | List chat threads (paginated) |
| GET | /api/v1/chats/:threadId/messages | Get messages in a thread |
| POST | /api/v1/chats/:threadId/messages | Send a message (SSE stream response) |
| DELETE | /api/v1/chats/:threadId | Delete a thread |
| PATCH | /api/v1/chats/:threadId/sharing | Update team sharing |
| PATCH | /api/v1/chats/:threadId/title | Generate and set thread title |
POST /api/v1/chats
Creates a new empty chat thread.
Request
No request body required.
Response 200 OK
| Field | Type | Description |
|---|---|---|
threadId | string (UUID) | The newly created thread's ID |
Example
POST /api/v1/chats/from-workflow
Creates a new chat thread linked to a specific workflow version. The specified version is copied into a draft for editing within the thread.
Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
workflowPublicId | string (UUID) | Yes | ID of the workflow to link |
versionPublicId | string (UUID) | No | Specific version ID; uses default version if omitted |
title | string | No | Custom title for the thread |
Response 201 Created
| Field | Type | Description |
|---|---|---|
threadId | string (UUID) | New thread ID |
workflowPublicId | string (UUID) | The linked workflow ID |
draftPublicId | string (UUID) | The new workflow draft created for this thread |
visibility | string | Always "owner" on creation |
Errors
| Status | Reason |
|---|---|
403 Forbidden | Insufficient access to the workflow |
404 Not Found | Workflow or version not found |
GET /api/v1/chats
Lists chat threads for the authenticated user, newest first.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number |
limit | number | 20 | Items per page |
Response 200 OK
Thread object fields:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Thread ID |
title | string | null | Thread title |
description | string | null | Thread description |
workflowId | string (UUID) | null | Associated workflow ID (if workflow thread) |
rule | object | null | Associated rule info (if rules thread): { id, name, description } |
lastUpdatedAt | string (ISO 8601) | Last activity timestamp |
sharedTeamKeys | string[] | Teams this thread is shared with |
Note: Threads shared with teams outside the user's membership are filtered out automatically.
GET /api/v1/chats/:threadId/messages
Retrieves messages in a thread along with the associated workflow/rule context.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
threadId | string (UUID) | Thread ID |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number |
limit | number | 20 | Items per page |
Response 200 OK
Message object fields:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Message ID |
role | "user" | "assistant" | Message author |
type | string | Message type (currently "text") |
content | string | Message text content |
createdAt | string (ISO 8601) | Creation timestamp |
Response top-level fields:
| Field | Type | Description |
|---|---|---|
messages | array | Paginated list of messages |
workflow | object | null | Current workflow definition in planner format (if workflow thread) |
workflowPublicId | string (UUID) | null | ID of linked workflow |
rule | object | null | Rule info { id, name, description } (if rules thread) |
rulePublicId | string (UUID) | null | ID of linked rule |
POST /api/v1/chats/:threadId/messages
Sends a message to the AI assistant in a thread and streams the response via SSE.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
threadId | string (UUID) | Thread ID |
Request Body (multipart/form-data)
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
message | string | Yes | – | The user's message text |
isInterrupt | boolean | No | false | Whether this is a response to an interrupt (AI is awaiting user input) |
interruptType | string | No | "workflow-inputs" | Type of interrupt: "workflow-inputs" or "subworkflow-select" |
inputs | JSON object | No | {} | Input values when responding to a workflow-inputs interrupt |
envs | JSON object | No | {} | Environment variable overrides (string-to-string map) |
selectedWorkflowId | string | No | – | Required when interruptType is "subworkflow-select" |
attachments | File[] | No | [] | File attachments (images, documents) |
model | string | No | "GPT-4o" | AI model to use (see available models below) |
Available models: GPT-4o, GPT-4o-mini, Claude-3-5-Sonnet, Claude-3-5-Haiku, Gemini-2.0-Flash, Gemini-2.5-Pro, DeepSeek-R1, o3-mini, o4-mini
Response
Returns an SSE stream (Content-Type: text/event-stream).
SSE Events:
| Event | Data | Description |
|---|---|---|
ping | { "content": "ping" } | Keep-alive, sent every 9 seconds |
message | { "content": "<text>" } | AI response text |
error | { "content": "<message>" } | Error during streaming |
Example (JavaScript)
Handling Interrupts
The AI may pause and request user input (an interrupt). When this happens, the SSE stream will emit a message indicating the interrupt type. Resume by sending another message with isInterrupt: true:
DELETE /api/v1/chats/:threadId
Soft-deletes a thread and all its messages.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
threadId | string (UUID) | Thread ID |
Response 200 OK
PATCH /api/v1/chats/:threadId/sharing
Updates the team access list for a thread. Replaces the existing sharing configuration (not a merge).
Path Parameters
| Parameter | Type | Description |
|---|---|---|
threadId | string (UUID) | Thread ID |
Request Body (JSON)
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
shareWithTeamKeys | string[] | Yes | [] | List of team keys to share with. Pass [] to make owner-only. |
Response 200 OK
Returns the updated sharing result object.
PATCH /api/v1/chats/:threadId/title
Generates an AI-powered title for the thread based on the provided conversation messages, then saves it.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
threadId | string (UUID) | Thread ID |
Request Body (JSON)
An array of conversation messages (1–20 messages):
Message object:
| Field | Type | Required | Description |
|---|---|---|---|
role | "user" | "assistant" | Yes | Message role |
content | array | Yes | Array of content parts: [{ "type": "text", "text": "..." }] |
Constraints: minimum 1 message, maximum 20 messages.