Create AIPrompt

Create a new AI prompt, optionally continuing an existing AI conversation from a previous prompt.

The API stores your message as an AI message and returns that message, the assistant reply, and any chart or dashboard assets the agent produced. Every request needs exactly one { type: "text" } input.

Which other inputs you can send depends on agent :

• dataset : item , analyst , dashboard , and auto . Add one entry per dataset. This limits the datasets the agent may use.

• item : item , analyst , and auto . An existing chart to update, explain, or use as a reference. Stored as an AI message asset on the user message.

• dashboard : analyst , dashboard , and auto .

Dataset inputs are stored on the user message so later turns can reuse them. For the dashboard and auto agents, a dashboard input is the dashboard to edit or continue, and it is stored as an AI message asset. For the analyst agent, it is the dashboard the user is viewing: charts in views → items , applied filters in runtimeFilters , and the title and description in meta . Analyst dashboard context is not stored as an asset. The auto agent also uses item and dashboard inputs when it plans data_analysis , chart_creation , or dashboard_creation steps.

Agents

• item : create, suggest, or explain one chart. task is "generate" , "suggest" , or "describe" . describe needs a chart already in the conversation.

• analyst : answer a question about your data in text, and optionally add a chart. Requires the Luzmo IQ add-on. Only task: "generate" .

• dashboard ( beta , selected customers; contact support@luzmo.com ): create a dashboard, or edit one passed as { type: "dashboard" } . Only task: "generate" and response_mode: "asset" or "mixed" . This call returns a dashboard asset and does not save it. Persist it with Create Dashboard or Update Dashboard .

• auto : plan a multi-step answer using data_analysis , chart_creation , and dashboard_creation . Requires the Luzmo IQ add-on. It accepts the same optional dataset , item , and dashboard inputs those capabilities need. Only task: "generate" . Omit capabilities to allow every capability available to the authenticated user.

Saved Agents

Pass a reusable Agent as agent_id . Its datasets and published Rules apply on top of the agent you select. agent is required.

• item , analyst , or dashboard : that agent runs, with its usual task and response_mode rules. The saved Agent's capabilities are not used.

• auto : the universal agent runs. It uses the saved Agent's capabilities, or every capability available to the user when the Agent has none. A capabilities list on this request replaces the Agent's list for this call.

Datasets. When the Agent has datasets, the request can use only those this user can access. With no dataset inputs, it uses all of them. Dataset inputs that are not on the Agent are ignored. If every requested dataset is outside the Agent, or an item input reads one (including through a formula), the API returns 403 Forbidden . An Agent with no datasets does not restrict datasets.

Rules and instructions. Only the published version of each linked Rule is used. Request context is combined with the Embed token's iq.context . Neither one replaces the other. The Agent's theme_id is not applied to returned assets.

The Agent must belong to the caller's organization. Anyone in that organization can run it. Any other agent_id returns 404 Not Found . See Creating and using Agents through the API for the full setup.

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 for a complete ordered sequence.