Create AIPrompt

LLM-friendly URL

POST

https://api.luzmo.com/0.1.0/aiprompt

API call form

Examples

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

When creating an AIPrompt via this service, the API persists the user message as an AI message , creates an AI conversation automatically when conversation_id is omitted, and returns the user's and assistant's created AI messages together with any assets generated (e.g. a visualization item). 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 associations on that message so they can be retrieved later.

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" .

(*) 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:

start event is emitted once after the user message has been persisted.
Zero or more progress events while the workflow is running.
For each assistant text block: text_start → one or more text_delta → text_end .
For each generated asset: asset_start → one or more asset_delta → asset_end .
Optionally an error event if the workflow fails.
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.

Request parameters

Response schema

Can be executed by:

Logged-in User

Can be associated to:

Did this page help you?

Yes

Language

Shell

Node

Java

.NET

Python

PHP

Install

pip install luzmo-sdk

Example Request

import Luzmo from '@luzmo/nodejs-sdk';
const client = new Luzmo({
  api_key: '<your Luzmo API key>',
  api_token: '<your Luzmo API token>',
  host: 'https://api.luzmo.com'
});


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"
      }
    ]
  }
);

Example Response

200

400

500

{
  "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"
      }
    ]
  }
}