--- title: Create AIPrompt url: https://developer.luzmo.com/api/createAIPrompt type: api resource: aiprompt action: create method: POST --- # Create AIPrompt Create a new AI prompt, optionally continuing an existing [AI conversation](api/searchAIConversation.md) from a previous prompt. When creating an AIPrompt via this service, the API persists the user message as an [AI message](/api/searchAIMessage.md), creates an [AI conversation](/api/searchAIConversation.md) automatically when `conversation_id` is omitted, and returns the user's and assistant's created AI messages together with any generated item or dashboard assets. Exactly one `text` input is required; optional `dataset` inputs are linked in the background as dataset/securable associations on the created user message, and optional `item` inputs are persisted in the background as [AIMessageAsset](/api/searchAIMessageAsset.md) associations on that message so they can be retrieved later. A `dashboard` input lets the `dashboard` agent edit or continue working on an existing dashboard; for the `analyst` agent, it supplies the dashboard state the user is viewing—its charts (`views` → `items`), applied filters (`runtimeFilters`), and title/description (`meta`)—to ground the answer. Analyst dashboard context is not persisted as an asset. ## Agents - `item`: generate, suggest, or describe a single Luzmo item (chart). Supports `task: "generate" | "suggest" | "describe"`. - _(*)_ `analyst`: IQ-backed data analysis that answers natural-language questions about your data (in text and/or with a visualization item). Only supports `task: "generate"`. - `dashboard`: generate a multi-item dashboard or edit an existing dashboard passed as `{ type: "dashboard" }` input. Only supports `task: "generate"` and `response_mode: "asset" | "mixed"`. The dashboard agent is currently in beta and is available to selected customers. To request access, contact [support@luzmo.com](mailto:support@luzmo.com). _(*) Requires the Luzmo IQ addon to be included in your license._ ## Streaming response Set `stream: true` in the request properties to receive progress, text, and asset events as they are produced instead of waiting for the full result. The endpoint supports two transports: - **HTTP (Server-Sent Events)**: the response is sent with `Content-Type: text/event-stream; charset=utf-8`, `Cache-Control: no-cache, no-transform`, `Connection: keep-alive`, and `Transfer-Encoding: chunked`. Each event is delivered as a single `data: {...}` frame, and the stream ends with a final `data: [DONE]` frame before the connection closes. - **Socket.IO**: connected socket clients receive the same JSON event objects on the `aiprompt` channel. The socket transport is used automatically when a socket is connected to the API and the same `aiprompt.create` payload is sent. Every event emitted contains a `type`, and after the first event also the streaming context fields `conversation_id`, `user_message_id`, and `assistant_message_id`. A typical stream produces events in this order: 1. `start` event is emitted once after the user message has been persisted. 2. Zero or more `progress` events while the workflow is running. Each event includes a full `progress` tree snapshot (nested nodes with `id`, `step`, `status`, optional `description`, `description_metadata`, and `children`). Replace your UI with the latest snapshot; do not depend on specific `step` names or `description` text, because they vary by agent, locale, and API version. 3. For each assistant text block: `text_start` → one or more `text_delta` → `text_end`. 4. For each generated asset: `asset_start` → one or more `asset_delta` → `asset_end`. Dashboard generation can stream progressive `dashboard-title`, `dashboard-layout`, and `dashboard-item` previews before the final authoritative `dashboard` asset. 5. Optionally an `error` event if the workflow fails. 6. A final `finish` event whose `result` matches the non-streaming response (or `null` if the workflow failed). See the "Streaming response" schema below for the exact payload of every event type, and the [streamed example](/api/createAIPrompt.md) for a complete ordered sequence. ## Endpoint - **Method**: `POST` (all Luzmo API calls use POST with an action parameter) - **Path**: `/aiprompt` - **Action**: `create` - **Base URL**: `https://api.luzmo.com` (EU), `https://api.us.luzmo.com` (US), or your VPC-specific API Host URL ## Request Parameters ### Available Parameters - **agent** (required): `"analyst" | "dashboard" | "item"` - Agent that should handle the prompt. - **task**: `"generate" | "suggest" | "describe"` - Task to execute for the selected agent. - Default: `"generate"` - **conversation_id**: `string (uuid)` - Existing conversation to continue. - **locale_id**: `string` - Locale for the generated response. - **timezone_id**: `string` - Timezone for date/time interpretation and output. - **text_format**: `"plain" | "markdown"` - Preferred format for text responses. - Default: `"plain"` - **stream**: `boolean` - When `true`, stream response events instead of waiting for a final payload. - Default: `false` - **response_mode**: `"text" | "asset" | "mixed"` - Preferred response shape. - Default: `"mixed"` - **generated_asset_locale_ids**: `array` - Locale IDs to use for generated assets. - **context**: `string` - Custom instructions for the `analyst` agent, merged with the Embed token's `iq.context`. - **input** (required): `array` - Ordered prompt inputs. **This parameter accepts exactly one of the following 4 variants:** --- ### Variant 1: Text prompt **Discriminator values** (use these to select this variant): - `type`: `"text"` **Required fields**: `type`, `text` **Properties**: - **type** **(required)**: `string` - Must be `"text"` - **text** **(required)**: `string` - Natural-language prompt to send to the selected agent. --- ### Variant 2: Dataset reference **Discriminator values** (use these to select this variant): - `type`: `"dataset"` **Required fields**: `type`, `id` **Properties**: - **type** **(required)**: `string` - Must be `"dataset"` - **id** **(required)**: `string (uuid)` - Dataset identifier. --- ### Variant 3: Item context **Discriminator values** (use these to select this variant): - `type`: `"item"` **Required fields**: `type`, `value` **Properties**: - **type** **(required)**: `string` - Must be `"item"` - **value** **(required)**: `object` - Luzmo [item JSON payload](/guide/ack--item-definitions.md). --- ### Variant 4: Dashboard context **Discriminator values** (use these to select this variant): - `type`: `"dashboard"` **Required fields**: `type`, `value` **Properties**: - **type** **(required)**: `string` - Must be `"dashboard"` - **value** **(required)**: `object` - Current dashboard state. - **type**: `string` - Must be `"dashboard"` - **id**: `string` - Optional dashboard identifier. - **contents**: `object` - Create-ready dashboard contents. - **views**: `array` - Dashboard views for the available screen modes in the legacy flat state shape. - Item properties: - **screenModus** **(required)**: `"desktop" | "tablet" | "mobile" | "largeScreen" | "fixed"` - Allowed values: `"desktop"`, `"tablet"`, `"mobile"`, `"largeScreen"`, `"fixed"` - **options**: `object` - **filterGroups**: `array` - **items**: `array` - **syncScreenModes**: `boolean` - **currentScreenMode**: `"desktop" | "tablet" | "mobile" | "largeScreen" | "fixed"` - Screen mode currently shown to the user. - Allowed values: `"desktop"`, `"tablet"`, `"mobile"`, `"largeScreen"`, `"fixed"` - **theme**: `object` - **name**: `object` - Localized dashboard name keyed by locale ID. - **runtimeFilters**: `array` - Live runtime filters supplied as read-only analyst context. - **meta**: `object` - Dashboard metadata supplied as read-only analyst context. - **title**: `string` - **description**: `string` ## Response Properties **The response is one of the following 2 formats:** --- ### Variant 1: Non-streaming response Default response when `stream` is `false`. **Properties**: - **conversation_id**: `string (uuid)` - Conversation identifier for the returned messages. - **user_message**: `object` - AI message returned inline by `aiprompt.create`. - **id**: `string (uuid)` - Unique identifier of the AI message. - **conversation_id**: `string (uuid)` - Identifier of the conversation that contains the message. - **message**: `string` - Human-readable text for the visible message. - **role**: `"system" | "user" | "assistant" | "tool" | "function"` - Role of the message author. - Allowed values: `"system"`, `"user"`, `"assistant"`, `"tool"`, `"function"` - **agent**: `"item" | "analyst" | "dashboard"` - Agent that handled the original prompt. - Allowed values: `"item"`, `"analyst"`, `"dashboard"` - **task**: `"generate" | "suggest" | "describe"` - Task executed for the original prompt. - Allowed values: `"generate"`, `"suggest"`, `"describe"` - **locale_id**: `string` - Locale used for the message. - **created_at**: `string (date-time)` - Timestamp when the message was created. - **updated_at**: `string (date-time)` - Timestamp when the message was last updated. - **aiMessageAssets**: `array` - Persisted assets returned inline with the message. - Item properties: - **id**: `string (uuid)` - Unique identifier of the AI message asset. - **message_id**: `string (uuid)` - Identifier of the AI message that owns this asset. - **type**: `"item" | "dashboard"` - Documented AI message asset type. - Allowed values: `"item"`, `"dashboard"` - **value**: `object` - Item or dashboard asset payload. - **created_at**: `string (date-time)` - Timestamp when the asset was created. - **updated_at**: `string (date-time)` - Timestamp when the asset was last updated. - **assistant_message**: `object` - Assistant message created for the prompt, if one was persisted. - **id**: `string (uuid)` - Unique identifier of the AI message. - **conversation_id**: `string (uuid)` - Identifier of the conversation that contains the message. - **message**: `string` - Human-readable text for the visible message. - **role**: `"system" | "user" | "assistant" | "tool" | "function"` - Role of the message author. - Allowed values: `"system"`, `"user"`, `"assistant"`, `"tool"`, `"function"` - **agent**: `"item" | "analyst" | "dashboard"` - Agent that handled the original prompt. - Allowed values: `"item"`, `"analyst"`, `"dashboard"` - **task**: `"generate" | "suggest" | "describe"` - Task executed for the original prompt. - Allowed values: `"generate"`, `"suggest"`, `"describe"` - **locale_id**: `string` - Locale used for the message. - **created_at**: `string (date-time)` - Timestamp when the message was created. - **updated_at**: `string (date-time)` - Timestamp when the message was last updated. - **aiMessageAssets**: `array` - Persisted assets returned inline with the message. - Item properties: - **id**: `string (uuid)` - Unique identifier of the AI message asset. - **message_id**: `string (uuid)` - Identifier of the AI message that owns this asset. - **type**: `"item" | "dashboard"` - Documented AI message asset type. - Allowed values: `"item"`, `"dashboard"` - **value**: `object` - Item or dashboard asset payload. - **created_at**: `string (date-time)` - Timestamp when the asset was created. - **updated_at**: `string (date-time)` - Timestamp when the asset was last updated. --- ### Variant 2: Streaming response Ordered sequence of `AIPromptStreamEvent` objects emitted when `stream` is `true`. **Array items**: - **Response type**: `array` **Each array item has the following properties:** **Each item is one of the following 10 types:** --- ### Variant 1: start **Discriminator values** (use these to select this variant): - `type`: `"start"` **Required fields**: `type`, `conversation_id`, `user_message_id`, `assistant_message_id` **Properties**: - **type** **(required)**: `string` - Must be `"start"` - **conversation_id** **(required)**: `string (uuid)` - Conversation identifier for the streamed prompt. - **user_message_id** **(required)**: `string (uuid)` - Persisted user message identifier. - **assistant_message_id** **(required)**: `string (uuid)` - Assistant message identifier reserved for the response. --- ### Variant 2: progress **Discriminator values** (use these to select this variant): - `type`: `"progress"` **Required fields**: `type`, `conversation_id`, `user_message_id`, `assistant_message_id`, `progress` **Properties**: - **type** **(required)**: `string` - Must be `"progress"` - **conversation_id** **(required)**: `string (uuid)` - **user_message_id** **(required)**: `string (uuid)` - **assistant_message_id** **(required)**: `string (uuid)` - **progress** **(required)**: `object` - Full snapshot of the workflow progress tree. Replace your rendered tree with each new event; tree shape and node contents are dynamic. - **id** **(required)**: `string` - Stable identifier for this node within the streamed progress tree. - **step** **(required)**: `string` - Internal workflow step identifier. Not part of the public contract—do not branch application logic on `step` values. - **status** **(required)**: `"pending" | "inProgress" | "success" | "error"` - Current state of this workflow step. - Allowed values: `"pending"`, `"inProgress"`, `"success"`, `"error"` - **description**: `string` - Optional display label (localized). May include `{{placeholder}}` tokens filled from `description_metadata`; wording can change between API versions. - **description_metadata**: `object` - Optional values substituted into `description` placeholders. - **children**: `array` - Nested workflow steps under this node. --- ### Variant 3: text_start **Discriminator values** (use these to select this variant): - `type`: `"text_start"` **Required fields**: `type`, `conversation_id`, `user_message_id`, `assistant_message_id`, `text_id` **Properties**: - **type** **(required)**: `string` - Must be `"text_start"` - **conversation_id** **(required)**: `string (uuid)` - **user_message_id** **(required)**: `string (uuid)` - **assistant_message_id** **(required)**: `string (uuid)` - **text_id** **(required)**: `string` - Identifier of the text block this event belongs to. --- ### Variant 4: text_delta **Discriminator values** (use these to select this variant): - `type`: `"text_delta"` **Required fields**: `type`, `conversation_id`, `user_message_id`, `assistant_message_id`, `text_id`, `delta` **Properties**: - **type** **(required)**: `string` - Must be `"text_delta"` - **conversation_id** **(required)**: `string (uuid)` - **user_message_id** **(required)**: `string (uuid)` - **assistant_message_id** **(required)**: `string (uuid)` - **text_id** **(required)**: `string` - Identifier of the text block this delta belongs to. - **delta** **(required)**: `string` - Text fragment to append to the in-progress text block. --- ### Variant 5: text_end **Discriminator values** (use these to select this variant): - `type`: `"text_end"` **Required fields**: `type`, `conversation_id`, `user_message_id`, `assistant_message_id`, `text_id` **Properties**: - **type** **(required)**: `string` - Must be `"text_end"` - **conversation_id** **(required)**: `string (uuid)` - **user_message_id** **(required)**: `string (uuid)` - **assistant_message_id** **(required)**: `string (uuid)` - **text_id** **(required)**: `string` - Identifier of the text block this event closes. --- ### Variant 6: asset_start **Discriminator values** (use these to select this variant): - `type`: `"asset_start"` **Required fields**: `type`, `conversation_id`, `user_message_id`, `assistant_message_id`, `asset_id`, `asset_type` **Properties**: - **type** **(required)**: `string` - Must be `"asset_start"` - **conversation_id** **(required)**: `string (uuid)` - **user_message_id** **(required)**: `string (uuid)` - **assistant_message_id** **(required)**: `string (uuid)` - **asset_id** **(required)**: `string` - Identifier of the asset block this event opens. - **asset_type** **(required)**: `string` - Type of asset being streamed. - Allowed values: `"item"`, `"item-suggestion"`, `"dashboard-title"`, `"dashboard-layout"`, `"dashboard-item"`, `"dashboard"` --- ### Variant 7: asset_delta **Discriminator values** (use these to select this variant): - `type`: `"asset_delta"` **Required fields**: `type`, `conversation_id`, `user_message_id`, `assistant_message_id`, `asset_id`, `delta` **Properties**: - **type** **(required)**: `string` - Must be `"asset_delta"` - **conversation_id** **(required)**: `string (uuid)` - **user_message_id** **(required)**: `string (uuid)` - **assistant_message_id** **(required)**: `string (uuid)` - **asset_id** **(required)**: `string` - Identifier of the asset block this delta updates. - **delta** **(required)**: `object` - Partial item, suggestion, or dashboard asset payload. --- ### Variant 8: asset_end **Discriminator values** (use these to select this variant): - `type`: `"asset_end"` **Required fields**: `type`, `conversation_id`, `user_message_id`, `assistant_message_id`, `asset_id` **Properties**: - **type** **(required)**: `string` - Must be `"asset_end"` - **conversation_id** **(required)**: `string (uuid)` - **user_message_id** **(required)**: `string (uuid)` - **assistant_message_id** **(required)**: `string (uuid)` - **asset_id** **(required)**: `string` - Identifier of the asset block this event closes. --- ### Variant 9: error **Discriminator values** (use these to select this variant): - `type`: `"error"` **Required fields**: `type`, `error_text` **Properties**: - **type** **(required)**: `string` - Must be `"error"` - **conversation_id**: `string (uuid)` - **user_message_id**: `string (uuid)` - **assistant_message_id**: `string (uuid)` - **error_text** **(required)**: `string` - Human-readable error message. --- ### Variant 10: finish **Discriminator values** (use these to select this variant): - `type`: `"finish"` **Required fields**: `type`, `result` **Properties**: - **type** **(required)**: `string` - Must be `"finish"` - **conversation_id**: `string (uuid)` - **user_message_id**: `string (uuid)` - **assistant_message_id**: `string (uuid)` - **result** **(required)**: `AIPromptResult` - Final result payload, or `null` when the workflow failed. ## Required Access Rights - Logged-in User ## SDK Usage Luzmo provides official SDKs that handle authentication and request formatting automatically. You can also use any HTTP client (curl, fetch, axios, etc.) to make requests directly to the API. ### Shell / cURL Base URL: `https://api.luzmo.com` (EU), `https://api.us.luzmo.com` (US), or your VPC-specific API Host URL ```bash curl https://api.luzmo.com/0.1.0/aiprompt -H "Content-Type: application/json" -d @- << EOF { "action": "create", "version": "0.1.0", "key": "", "token": "", "properties": { "agent": "item", "task": "generate", "response_mode": "mixed", "locale_id": "en", "input": [ { "type": "text", "text": "Show monthly revenue as a line chart." }, { "type": "dataset", "id": "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" } ] } } EOF ``` ### Node SDK Install: `npm install @luzmo/nodejs-sdk` ```javascript import Luzmo from '@luzmo/nodejs-sdk'; const client = new Luzmo({ api_key: '', api_token: '', host: '< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >' }); const response = await client.create('aiprompt', { agent: "item", task: "generate", response_mode: "mixed", locale_id: "en", input: [ { type: "text", text: "Show monthly revenue as a line chart." }, { type: "dataset", id: "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" } ] } ); ``` ### Java SDK Install: `pkg:maven/com.luzmo/sdk` ```java Luzmo client = new Luzmo( "', "', "< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >" ); JSONObject response = client.create("aiprompt", ImmutableMap.of( "agent" , "item", "task" , "generate", "response_mode" , "mixed", "locale_id" , "en", "input" , ImmutableList.of( ImmutableMap.of( "type" , "text", "text" , "Show monthly revenue as a line chart." ), ImmutableMap.of( "type" , "dataset", "id" , "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" ) ) ) ); ``` ### .NET SDK Install: `dotnet add package LuzmoSDK` ```csharp Luzmo client = new Luzmo( "', "', "< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >" ); dynamic properties = new ExpandoObject(); properties.agent = "item"; properties.task = "generate"; properties.response_mode = "mixed"; properties.locale_id = "en"; properties.input = new List { new { type = "text", text = "Show monthly revenue as a line chart." }, new { type = "dataset", id = "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" } }; dynamic response = client.create("aiprompt", properties); ``` ### Python SDK Install: `pip install luzmo-sdk` ```python from luzmo.luzmo import Luzmo client = Luzmo( "', "', "< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >" ) response = client.create("aiprompt", { "agent": "item", "task": "generate", "response_mode": "mixed", "locale_id": "en", "input": [ { "type": "text", "text": "Show monthly revenue as a line chart." }, { "type": "dataset", "id": "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" } ] } ) ``` ### PHP SDK Install: `composer require luzmo/luzmo-sdk-php` ```php ', '', '< https://api.luzmo.com (default) or https://api.us.luzmo.com or your VPC-specific address >' ); $response = $client->create("aiprompt", array ( 'agent' => "item", 'task' => "generate", 'response_mode' => "mixed", 'locale_id' => "en", 'input' => array ( array ( 'type' => "text", 'text' => "Show monthly revenue as a line chart." ), array ( 'type' => "dataset", 'id' => "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" ) ) ) ); ?> ``` ## Request Body Examples The following examples show the complete request body structure for HTTP/cURL requests. Each example includes the outer wrapper property (`properties`) that contains the actual parameters. > **For SDKs**: Pass only the inner content (without the outer wrapper) to the SDK methods. For example, if the JSON shows `{ "properties": { "name": {"en": "My aiprompt"} } }`, an SDK would use something like this: `client.create('aiprompt', { name: { en: "My aiprompt" } })`. ### Generate a chart with the item agent, limited to one dataset **Request properties:** ```json { "properties": { "agent": "item", "task": "generate", "response_mode": "mixed", "locale_id": "en", "input": [ { "type": "text", "text": "Show monthly revenue as a line chart." }, { "type": "dataset", "id": "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" } ] } } ``` **Expected response for this request (HTTP 200)** ```json { "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message": { "id": "1f3bb2f4-7589-40bc-b7d2-9a84b446d9ef", "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "message": "Show monthly revenue as a line chart.", "role": "user", "agent": "item", "task": "generate", "locale_id": "en", "created_at": "2026-05-14T10:03:11.000Z", "updated_at": "2026-05-14T10:03:11.000Z", "aiMessageAssets": [] }, "assistant_message": { "id": "2fdbacdc-d6e6-4a73-b22c-c4b6e9a10d98", "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "message": "Created a visualization.", "role": "assistant", "agent": null, "task": null, "locale_id": "en", "created_at": "2026-05-14T10:03:13.000Z", "updated_at": "2026-05-14T10:03:13.000Z", "aiMessageAssets": [ { "id": "7bfcf7ff-dcb2-4963-9e9b-0fe651a342af", "message_id": "2fdbacdc-d6e6-4a73-b22c-c4b6e9a10d98", "type": "item", "value": { "type": "line-chart", "options": {}, "slots": [], "filters": [] }, "created_at": "2026-05-14T10:03:13.000Z", "updated_at": "2026-05-14T10:03:13.000Z" } ] } } ``` ### Stream a prompt over SSE using item context **Request properties:** ```json { "properties": { "agent": "item", "task": "generate", "stream": true, "response_mode": "mixed", "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "input": [ { "type": "text", "text": "Update the chart to compare monthly revenue and costs." }, { "type": "item", "value": { "type": "line-chart", "options": {}, "slots": [], "filters": [] } } ] } } ``` **Expected response for this request (HTTP 200)** Raw HTTP response body when `stream` is `true`. Each event is sent as a single `data: ` Server-Sent Events frame, and the stream ends with `data: [DONE]`. Socket.IO clients receive the same JSON objects (without the `data:` prefix) on the `aiprompt` channel. The `progress` tree in this example is illustrative: `step` values, descriptions, and nesting vary by agent and workflow—render whatever tree the API sends and replace it on each `progress` event. ```text data: { "type":"start", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "assistant_message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f" } data: { "type":"progress", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "assistant_message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "progress":{ "id":"root", "step":"root", "status":"inProgress", "children":[ { "id":"event-13-102", "step":"iqDatasets", "status":"success", "description":"Retrieving datasets", "children":[ { "id":"event-14-696", "step":"iqDatasets.retrievingDatasets", "status":"success", "description":"Checking available datasets" }, { "id":"event-15-403", "step":"iqDatasets.result", "status":"success", "description":"Shortlisted datasets to consider: {{datasets}}", "description_metadata":{ "datasets":[ "sales-dataset", "revenue-dataset" ] } } ] }, { "id":"event-20-501", "step":"generateVisualization", "status":"inProgress", "description":"Generating visualization" } ] } } data: { "type":"text_start", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "assistant_message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "text_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f:text" } data: { "type":"text_delta", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "assistant_message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "text_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f:text", "delta":"Created a visualization." } data: { "type":"text_end", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "assistant_message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "text_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f:text" } data: { "type":"asset_start", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "assistant_message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "asset_id":"7bfcf7ff-dcb2-4963-9e9b-0fe651a342af", "asset_type":"item" } data: { "type":"asset_delta", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "assistant_message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "asset_id":"7bfcf7ff-dcb2-4963-9e9b-0fe651a342af", "delta":{ "type":"line-chart", "options":{...}, "slots":[...], "filters":[...] } } data: { "type":"asset_end", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "assistant_message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "asset_id":"7bfcf7ff-dcb2-4963-9e9b-0fe651a342af"} data: { "type":"finish", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "assistant_message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "result":{ "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message":{ "id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "message":"Update the chart to compare monthly revenue and costs.", "role":"user", "agent":"item", "task":"generate", "locale_id":"en", "created_at":"2026-05-14T10:15:24.000Z", "updated_at":"2026-05-14T10:15:24.000Z", "aiMessageAssets":[ { "id":"1c302f96-f568-46c2-a64f-9db4ae2d78eb", "message_id":"4a1289fb-2892-4fd6-8c3c-b0709a5ec2bb", "type":"item", "value":{ "type":"line-chart", "options":{...}, "slots":[...], "filters":[...] }, "created_at":"2026-05-14T10:15:24.000Z", "updated_at":"2026-05-14T10:15:24.000Z" } ] }, "assistant_message":{ "id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "conversation_id":"fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "message":"Created a visualization.", "role":"assistant", "agent":null, "task":null, "locale_id":"en", "created_at":"2026-05-14T10:15:26.000Z", "updated_at":"2026-05-14T10:15:26.000Z", "aiMessageAssets":[ { "id":"7bfcf7ff-dcb2-4963-9e9b-0fe651a342af", "message_id":"40a580e6-75c2-434d-9dbd-4fa1b5d7791f", "type":"item", "value":{ "type":"line-chart", "options":{...}, "slots":[...], "filters":[...] }, "created_at":"2026-05-14T10:15:26.000Z", "updated_at":"2026-05-14T10:15:26.000Z" } ] } } } data: [DONE] ``` ### Answer with the analyst agent using dashboard context **Request properties:** ```json { "properties": { "agent": "analyst", "task": "generate", "response_mode": "text", "text_format": "markdown", "locale_id": "en", "input": [ { "type": "text", "text": "Why did revenue drop compared to last quarter?" }, { "type": "dashboard", "value": { "currentScreenMode": "desktop", "meta": { "title": "Sales overview", "description": "Quarterly revenue and pipeline KPIs for the EMEA region." }, "views": [ { "screenModus": "desktop", "items": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "type": "line-chart", "options": { "title": { "en": "Revenue by quarter" } }, "slots": [ { "name": "x-axis", "content": [ { "label": { "en": "Quarter" } } ] }, { "name": "measure", "content": [ { "label": { "en": "Revenue" } } ] } ], "filters": [] } ] } ], "runtimeFilters": [ { "condition": "and", "origin": "global", "datasetId": "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a", "filters": [ { "expression": "? in ?", "parameters": [ { "datasetId": "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a", "columnId": "9b1c2d3e-4f56-7890-abcd-ef0123456789" }, [ "EMEA" ] ] } ] } ] } }, { "type": "dataset", "id": "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" } ] } } ``` **Expected response for this request (HTTP 200)** ```json { "conversation_id": "c1d2e3f4-a5b6-4788-9a0b-1c2d3e4f5a6b", "user_message": { "id": "d2e3f4a5-b6c7-4899-a0b1-2c3d4e5f6a7b", "conversation_id": "c1d2e3f4-a5b6-4788-9a0b-1c2d3e4f5a6b", "message": "Why did revenue drop compared to last quarter?", "role": "user", "agent": "analyst", "task": "generate", "locale_id": "en", "created_at": "2026-05-14T10:30:11.000Z", "updated_at": "2026-05-14T10:30:11.000Z", "aiMessageAssets": [] }, "assistant_message": { "id": "e3f4a5b6-c7d8-490a-b1c2-3d4e5f6a7b8c", "conversation_id": "c1d2e3f4-a5b6-4788-9a0b-1c2d3e4f5a6b", "message": "For the EMEA region, revenue is down 12% quarter over quarter, driven mainly by a drop in new deals in the Enterprise segment. Existing-customer revenue stayed flat.", "role": "assistant", "agent": null, "task": null, "locale_id": "en", "created_at": "2026-05-14T10:30:14.000Z", "updated_at": "2026-05-14T10:30:14.000Z", "aiMessageAssets": [] } } ``` ### Generate a dashboard with the dashboard agent **Request properties:** ```json { "properties": { "agent": "dashboard", "task": "generate", "response_mode": "mixed", "locale_id": "en", "input": [ { "type": "text", "text": "Build a sales overview dashboard with KPI tiles, a monthly revenue line chart, and a top products bar chart." }, { "type": "dataset", "id": "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" } ] } } ``` **Expected response for this request (HTTP 200)** ```json { "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message": { "id": "8a3c1e2f-4b5d-6e7f-8091-a2b3c4d5e6f7", "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "message": "Build a sales overview dashboard with KPI tiles, a monthly revenue line chart, and a top products bar chart.", "role": "user", "agent": "dashboard", "task": "generate", "locale_id": "en", "created_at": "2026-05-14T10:20:11.000Z", "updated_at": "2026-05-14T10:20:11.000Z", "aiMessageAssets": [] }, "assistant_message": { "id": "a5c6d7e8-f901-2345-6789-abcdef012345", "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "message": "Generated a sales overview dashboard with three items.", "role": "assistant", "agent": null, "task": null, "locale_id": "en", "created_at": "2026-05-14T10:20:18.000Z", "updated_at": "2026-05-14T10:20:18.000Z", "aiMessageAssets": [ { "id": "b6d7e8f9-0123-4567-89ab-cdef01234567", "message_id": "a5c6d7e8-f901-2345-6789-abcdef012345", "type": "dashboard", "value": { "name": { "en": "Sales overview" }, "contents": { "version": "0.1.100", "timezone": { "type": "fixed", "id": "UTC" }, "syncScreenModes": true, "datasetLinks": {}, "parameters": [], "views": [ { "screenModus": "desktop", "options": { "theme": { "id": "default" } }, "filterGroups": [], "items": [ { "id": "96721b1e-45f3-4f8f-bd39-cdfef03d5d53", "type": "conditional-number", "options": {}, "slots": [], "position": { "col": 0, "row": 0, "sizeX": 12, "sizeY": 8 } }, { "id": "d1d4c468-3597-4c0d-b8d3-5e94bf4337fe", "type": "line-chart", "options": {}, "slots": [], "position": { "col": 12, "row": 0, "sizeX": 24, "sizeY": 16 } }, { "id": "22acfc19-5654-4aa8-a9de-4f5b610e6374", "type": "bar-chart", "options": {}, "slots": [], "position": { "col": 0, "row": 16, "sizeX": 24, "sizeY": 16 } } ] } ] } }, "created_at": "2026-05-14T10:20:18.000Z", "updated_at": "2026-05-14T10:20:18.000Z" } ] } } ``` ### Add a detail table to an existing dashboard **Request properties:** ```json { "properties": { "agent": "dashboard", "task": "generate", "response_mode": "mixed", "locale_id": "en", "input": [ { "type": "text", "text": "Add a detail table at the bottom of the dashboard." }, { "type": "dataset", "id": "1ecf1fd1-cf74-47f8-9f73-aed6ea6ad44a" }, { "type": "dashboard", "value": { "type": "dashboard", "id": "6c07f5b4-3f8c-4fa3-ae17-6ff90b1f311f", "name": { "en": "Sales overview" }, "currentScreenMode": "desktop", "contents": { "version": "0.1.100", "timezone": { "type": "fixed", "id": "UTC" }, "syncScreenModes": true, "datasetLinks": {}, "parameters": [], "views": [ { "screenModus": "desktop", "options": { "theme": { "id": "default" } }, "filterGroups": [], "items": [ { "id": "c29a4540-2eb0-4306-94a0-dda07908cf4d", "type": "bar-chart", "options": { "title": { "en": "Monthly revenue" } }, "slots": [], "position": { "col": 0, "row": 0, "sizeX": 48, "sizeY": 16 } } ] } ] } } } ] } } ``` **Expected response for this request (HTTP 200)** ```json { "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "user_message": { "id": "c1d2e3f4-5678-4901-8234-56789abcdef0", "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "message": "Add a detail table at the bottom of the dashboard.", "role": "user", "agent": "dashboard", "task": "generate", "locale_id": "en", "created_at": "2026-05-14T10:30:11.000Z", "updated_at": "2026-05-14T10:30:11.000Z", "aiMessageAssets": [ { "id": "d2e3f4a5-6789-4012-9345-6789abcdef01", "message_id": "c1d2e3f4-5678-4901-8234-56789abcdef0", "type": "dashboard", "value": { "type": "dashboard", "id": "6c07f5b4-3f8c-4fa3-ae17-6ff90b1f311f", "name": { "en": "Sales overview" }, "currentScreenMode": "desktop", "contents": { "version": "0.1.100", "timezone": { "type": "fixed", "id": "UTC" }, "syncScreenModes": true, "datasetLinks": {}, "parameters": [], "views": [ { "screenModus": "desktop", "options": { "theme": { "id": "default" } }, "filterGroups": [], "items": [ { "id": "c29a4540-2eb0-4306-94a0-dda07908cf4d", "type": "bar-chart", "options": { "title": { "en": "Monthly revenue" } }, "slots": [], "position": { "col": 0, "row": 0, "sizeX": 48, "sizeY": 16 } } ] } ] } }, "created_at": "2026-05-14T10:30:11.000Z", "updated_at": "2026-05-14T10:30:11.000Z" } ] }, "assistant_message": { "id": "e3f4a5b6-7890-4123-a456-789abcdef012", "conversation_id": "fdce930b-4f6d-4d2b-8a43-7ea7d62457a2", "message": "Added a detail table at the bottom of the dashboard.", "role": "assistant", "agent": null, "task": null, "locale_id": "en", "created_at": "2026-05-14T10:30:18.000Z", "updated_at": "2026-05-14T10:30:18.000Z", "aiMessageAssets": [ { "id": "f4a5b6c7-8901-4234-b567-89abcdef0123", "message_id": "e3f4a5b6-7890-4123-a456-789abcdef012", "type": "dashboard", "value": { "type": "dashboard", "id": "6c07f5b4-3f8c-4fa3-ae17-6ff90b1f311f", "name": { "en": "Sales overview" }, "contents": { "version": "0.1.100", "timezone": { "type": "fixed", "id": "UTC" }, "syncScreenModes": true, "datasetLinks": {}, "parameters": [], "views": [ { "screenModus": "desktop", "options": { "theme": { "id": "default" } }, "filterGroups": [], "items": [ { "id": "c29a4540-2eb0-4306-94a0-dda07908cf4d", "type": "bar-chart", "options": { "title": { "en": "Monthly revenue" } }, "slots": [], "position": { "col": 0, "row": 0, "sizeX": 48, "sizeY": 16 } }, { "id": "19ad8c3d-476f-41cc-809c-47584785a358", "type": "regular-table", "options": {}, "slots": [], "position": { "col": 0, "row": 16, "sizeX": 48, "sizeY": 16 } } ] } ] } }, "created_at": "2026-05-14T10:30:18.000Z", "updated_at": "2026-05-14T10:30:18.000Z" } ] } } ``` ## Generic Response Formats These responses are generic endpoint-level formats (for example common error payloads) and are not specific to one request example. ### A bad request error message returned by the API. (HTTP 400) ```json { "type": { "code": 400, "description": "Bad Request" }, "message": "Detailed error message" } ``` ### An internal server error message returned by the API. (HTTP 500) ```json { "type": { "code": 500, "description": "Internal Server Error" }, "message": "Detailed error message" } ``` --- ## Sitemap - [Official best practices and implementation guidelines](https://developer.luzmo.com/AGENTS.md) - [Overview of all docs pages](https://developer.luzmo.com/llms.txt) - [Full index of all documentation](https://developer.luzmo.com/llms-full.txt): Complete list of every doc page in markdown format with descriptions — use to discover relevant docs from user queries