Skip to main content
A Chat is the top-level container for every conversation in VyomFlow. It holds an ordered sequence of messages and serves as the entry point for every interaction you have with an agent. Every message you send and every agent run you trigger happens inside a specific chat.

​
The Chat object

Each chat is represented by a JSON object with the following fields:
​
string
required
Unique identifier for the chat (UUIDv4).
​
string
required
Display title of the chat. Auto-generated from the first user message if not provided during creation.
​
string | null
ISO 8601 timestamp when the chat was pinned, or null if it is not pinned. Updated by toggling the pinned state.
​
string
required
ISO 8601 timestamp when the chat was created. This value never changes.
​
string
required
ISO 8601 timestamp when the chat was last updated (new message, pin toggle, or other mutation). Ordered chronologically.
​
string | null
The ID of the currently active agent run inside this chat, or null when no run is in progress. While this is set, sending another message returns a 409 CONFLICT.

​
Lifecycle

A chat moves through a simple lifecycle from creation to archival.
1

Create a chat

Send a POST request to /api/v1/chats. You can optionally provide a title. If omitted, the title is set automatically from the first user message.
2

Send messages

Add messages by posting to /api/v1/chats/{chatId}/messages. Each message becomes part of the chat’s history and updates updatedAt.
3

Wait for the run to finish

Only one run can be active inside a chat at any time. The activeRunId field tells you whether a run is currently in progress. If you try to send a new message while activeRunId is set, the API returns 409 CONFLICT.
4

Delete when done

Remove a chat and all its contents with DELETE /api/v1/chats/{chatId}. This action is permanent and cannot be undone.

​
Pinning

Pinning lets you mark important chats so they are easy to find. Pinning is a toggle: calling the pin endpoint repeatedly switches the state on and off.
POST /api/v1/chats/{chatId}/pin
When you pin a chat, pinnedAt is set to the current ISO 8601 timestamp. When you unpin it, pinnedAt becomes null. The updatedAt field is also updated every time the pinned state changes.

​
Listing and filtering

To retrieve the chats you have access to, send a GET request to the chats collection endpoint.
GET /api/v1/chats
The response is a paginated list ordered by updatedAt in descending order, so the most recently active chats appear first. Use query parameters to navigate pages. If a chat is owned by another user, it is not included in the results because VyomFlow returns 404 for resources outside your ownership scope rather than 403. Now that you understand how chats work, you can read about runs to learn what happens after you send a message, or check the full API reference for every endpoint related to chats.