Create & List Chats

Create new chat sessions, list existing ones, and retrieve message history for AI-assisted workflows.

Chat is the recommended surface for blueprint authoring and graph edits. Use the REST blueprint endpoints for deterministic lifecycle operations like create, clone, inspect, and run.

Create a Chat

POST/api/v1/chats

Parameter	Type	Required	Description
title	string	No	Optional display title for the chat session
blueprintId	string	No	Optional blueprint ID to scope the chat to a specific workflow

Response (201 Created)

{
  "chatId": "chat_...",
  "title": "My project chat",
  "blueprintId": null,
  "createdAt": "2025-06-01T12:00:00Z"
}

List Chats

GET/api/v1/chats

Parameter	Type	Required	Description
limit	integer	No	Number of chats to return (default 20)
offset	integer	No	Pagination offset (default 0)

Response

{
  "chats": [
    {
      "chatId": "chat_...",
      "title": "My project chat",
      "createdAt": "2025-06-01T12:00:00Z",
      "updatedAt": "2025-06-02T09:30:00Z"
    }
  ],
  "total": 42,
  "hasNextPage": true,
  "hasPreviousPage": false
}

Get Chat Messages

GET/api/v1/chats/{chatId}/messages

Retrieve all messages in a chat session. The chatId is provided as a path parameter.

Response

{
  "chatId": "00000000-0000-0000-0000-000000000000",
  "messages": [
    {
      "messageId": "msg_...",
      "role": "user",
      "parts": [{ "type": "text", "text": "Create a 15-second product video" }],
      "createdAt": "2025-06-01T12:01:00Z"
    },
    {
      "messageId": "msg_...",
      "role": "assistant",
      "parts": [
        {
          "type": "text",
          "text": "I'll create a product video for you. What style would you like?"
        }
      ],
      "createdAt": "2025-06-01T12:01:02Z"
    }
  ]
}