Agent Chat API

Interact with AI agent workflows through a chat interface. Create sessions, send messages with streaming responses, and manage conversation history.

Create Session

POST

/api/agent-chat/sessions

Create a new chat session with an AI agent workflow

Request Body

Field	Type	Required	Description
`workflowId`	UUID	Yes	The AI agent workflow to chat with
`teamId`	UUID	Yes	Team context
`title`	string	No	Optional session title (auto-generated if omitted)

Request

{
  "workflowId": "uuid",
  "teamId": "uuid",
  "title": "Customer support conversation"
}

Response

201 Created

{
  "id": "uuid",
  "workflowId": "uuid",
  "title": "Customer support conversation",
  "createdAt": "2026-02-17T10:00:00.000Z",
  "messages": []
}

List Sessions

GET

/api/agent-chat/sessions

List chat sessions with optional search

Query Parameters

Parameter	Type	Required	Description
`teamId`	UUID	Yes	Team to list sessions for
`workflowId`	UUID	No	Filter by agent workflow
`search`	string	No	Search session titles and messages
`page`	integer	No	Page number (default: 0)
`size`	integer	No	Page size (default: 20)

Response

200 OK

{
  "content": [
    {
      "id": "uuid",
      "workflowId": "uuid",
      "title": "Customer support conversation",
      "messageCount": 12,
      "createdAt": "2026-02-17T10:00:00.000Z",
      "lastMessageAt": "2026-02-17T10:15:00.000Z"
    }
  ],
  "totalElements": 8,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

Get Session

GET

/api/agent-chat/sessions/:id

Get a session with its full message history

Response

200 OK

{
  "id": "uuid",
  "workflowId": "uuid",
  "title": "Customer support conversation",
  "createdAt": "2026-02-17T10:00:00.000Z",
  "messages": [
    {
      "id": "uuid",
      "role": "user",
      "content": "How do I reset my password?",
      "createdAt": "2026-02-17T10:01:00.000Z"
    },
    {
      "id": "uuid",
      "role": "assistant",
      "content": "You can reset your password by...",
      "createdAt": "2026-02-17T10:01:03.000Z",
      "tokenUsage": { "input": 45, "output": 128 }
    }
  ]
}

Send Message

POST

/api/agent-chat/sessions/:id/messages

Send a message and receive a streaming AI response

Request Body

Field	Type	Required	Description
`content`	string	Yes	The message text to send

Request

{
  "content": "How do I reset my password?"
}

Response (Server-Sent Events)

The response is streamed using Server-Sent Events (SSE). Each event contains a chunk of the AI agent's response:

SSE stream

event: message
data: {"type": "chunk", "content": "You can "}

event: message
data: {"type": "chunk", "content": "reset your password "}

event: message
data: {"type": "chunk", "content": "by visiting the settings page."}

event: message
data: {"type": "done", "tokenUsage": {"input": 45, "output": 128}}

Streaming

The response uses Content-Type: text/event-stream. Use an SSE client (e.g. EventSource) or read the stream manually. The final event has type: "done" to signal completion.

Update Session Title

PUT

/api/agent-chat/sessions/:id

Update the title of a chat session

Request Body

Field	Type	Required	Description
`title`	string	Yes	New session title

Request

{
  "title": "Password reset help"
}

Response

200 OK

{
  "id": "uuid",
  "title": "Password reset help",
  "updatedAt": "2026-02-17T10:20:00.000Z"
}

Delete Session

DELETE

/api/agent-chat/sessions/:id

Delete a chat session and all its messages

Permanently removes the session and all associated messages. This action cannot be undone.

Response

200 OK

{
  "message": "Session deleted successfully"
}

Clear Session Messages

POST

/api/agent-chat/sessions/:id/clear

Clear all messages in a session while keeping the session

Removes all messages from the session but keeps the session itself intact. Useful for resetting a conversation without creating a new session.

Response

200 OK

{
  "message": "Session messages cleared",
  "sessionId": "uuid"
}

Error Codes

Status	Meaning
`400`	Invalid request body or missing required fields
`403`	User does not have access to this team or session
`404`	Session or workflow not found
`422`	Workflow is not an AI agent workflow or is inactive

Credentials

Widgets