# Luzmo Developer Documentation

> Luzmo is an embedded analytics platform that enables developers to integrate powerful data visualizations, dashboards, and AI-powered analytics into their applications. This documentation covers the Core API for backend operations and the Flex SDK for frontend visualizations.

## Documentation Structure

- [API Documentation](https://developer.luzmo.com/assets/llm-resources/llms-api.txt): Complete Core API reference including endpoints, entities, actions, and SDK examples
- [Flex SDK Documentation](https://developer.luzmo.com/assets/llm-resources/llms-flex.txt): Frontend visualization SDK with chart types, slots, options, and filters
- [AGENTS.md](https://developer.luzmo.com/assets/llm-resources/AGENTS.md): Instructions for AI coding assistants

## API Overview

The Luzmo Core API uses an action-based design where all requests are POST requests with an `action` parameter. This unified approach simplifies integration and provides consistent behavior across all operations. Authentication requires an API key and token pair.

**IMPORTANT**: The Luzmo API does NOT use traditional REST HTTP verbs (GET, PUT, DELETE). All operations use POST with an action parameter in the request body.

### Endpoints

- **EU (Default)**: `https://api.luzmo.com/0.1.0`
- **US**: `https://api.us.luzmo.com/0.1.0`
- **VPC**: `https://api.{vpc}.luzmo.com/0.1.0` (custom deployment)

### API Actions

All requests use POST to `/{resource}` with an `action` field specifying the operation:

- `create` - Create new resource (POST with action: "create")
- `get` - Retrieve resources by ID or filters (POST with action: "get")
- `update` - Modify existing resource (POST with action: "update")
- `delete` - Remove resource (POST with action: "delete")
- `associate` - Link two resources together (POST with action: "associate")
- `dissociate` - Unlink two resources (POST with action: "dissociate")

Example request structure:
```json
POST /securable
{
  "action": "create",
  "key": "<api-key>",
  "token": "<api-token>",
  "version": "0.1.0",
  "properties": { "type": "dashboard", "name": { "en": "My Dashboard" } }
}
```

> **IMPORTANT**: Dashboards and datasets are both "securables". All operations must use the `securable` resource with `type: 'dashboard'` or `type: 'dataset'`. There is no `/dashboard` endpoint.

### OpenAPI Schema Note

The OpenAPI schema at `/assets/oas/oas-luzmo-full.json` documents the Luzmo API's action-based endpoints. Each operation is defined as a POST endpoint with `?action` query parameter (e.g., `/securable?create`, `/user?get`). When using the SDKs, you call methods like `client.create()`, `client.get()` which handle this automatically.

**When in doubt**: First consult [llms-api.txt](https://developer.luzmo.com/assets/llm-resources/llms-api.txt) for detailed API patterns and entity mappings. For complete request body specifications and response examples, see the OpenAPI schema.

### API Entities (Resources)

Core entities available via API:
- **Authorization**: Embed tokens for secure frontend access
- **Securable**: **Both dashboards AND datasets** - use `type: 'dashboard'` or `type: 'dataset'`
  - All dashboard/dataset operations use `client.get('securable', ...)`, `client.create('securable', ...)`, etc.
  - There is NO `/dashboard` endpoint - using it will fail

> **Dashboard Versioning**: Dashboard `contents` are versioned (current: **v0.1.97**). The structure changes between versions. Luzmo auto-upgrades dashboards to newer versions. When programmatically creating/modifying dashboard contents, use the correct schema structure for your target version.
- **Column**: Dataset columns with type metadata
- **User**: User accounts and permissions
- **Group**: User groups for access control
- **Organization**: Multi-tenant organization management
- **Collection**: Dashboard groupings
- **Formula**: Calculated metrics and aggregations
- **Theme**: Visual styling configurations
- **Schedule**: Automated reporting schedules
- **Data**: Query service for retrieving aggregated data

Full API reference: https://developer.luzmo.com/guide/api--introduction

## Flex SDK Overview

Luzmo Flex SDK enables code-first data visualizations that can be embedded in any web application.

> **Important: Chart Sizing** - Charts require explicit dimensions to render. Place charts in containers with defined height/width, or set dimensions directly on the component.

### Chart Types

**Current Schema Version: v0.1.97**

> **Version Note**: This documentation describes chart configuration for schema version **0.1.97**. Chart schemas are versioned and the structure may differ between versions. Always use the schema version that matches your implementation. Luzmo automatically upgrades dashboard contents to newer versions, but when creating charts programmatically, ensure you use the correct schema structure for your target version.

46 visualization types. Each chart type has a JSON schema defining its available options and slots.

**Schema Base URL**: `https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/`

| Category | Chart Types | Schema Links |
|----------|-------------|--------------|
| **Standard Charts** | area-chart, bar-chart, column-chart, line-chart, donut-chart, funnel-chart, scatter-plot, bubble-chart, radar-chart, combination-chart, pyramid-chart | [area-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/area-chart.schema.json), [bar-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/bar-chart.schema.json), [column-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/column-chart.schema.json), [line-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/line-chart.schema.json), [donut-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/donut-chart.schema.json), [funnel-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/funnel-chart.schema.json), [scatter-plot](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/scatter-plot.schema.json), [bubble-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/bubble-chart.schema.json), [radar-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/radar-chart.schema.json), [combination-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/combination-chart.schema.json), [pyramid-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/pyramid-chart.schema.json) |
| **Tables** | regular-table, pivot-table, heat-table | [regular-table](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/regular-table.schema.json), [pivot-table](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/pivot-table.schema.json), [heat-table](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/heat-table.schema.json) |
| **Maps** | choropleth-map, marker-map, hexbin-map, symbol-map, route-map, spike-map | [choropleth-map](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/choropleth-map.schema.json), [marker-map](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/marker-map.schema.json), [hexbin-map](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/hexbin-map.schema.json), [symbol-map](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/symbol-map.schema.json), [route-map](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/route-map.schema.json), [spike-map](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/spike-map.schema.json) |
| **Gauges & Numbers** | circular-gauge, speedometer-chart, bullet-chart, evolution-number, conditional-number | [circular-gauge](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/circular-gauge.schema.json), [speedometer-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/speedometer-chart.schema.json), [bullet-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/bullet-chart.schema.json), [evolution-number](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/evolution-number.schema.json), [conditional-number](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/conditional-number.schema.json) |
| **Filters** | date-filter, dropdown-filter, slicer-filter, slider-filter, search-filter | [date-filter](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/date-filter.schema.json), [dropdown-filter](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/dropdown-filter.schema.json), [slicer-filter](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/slicer-filter.schema.json), [slider-filter](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/slider-filter.schema.json), [search-filter](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/search-filter.schema.json) |
| **Hierarchical** | treemap-chart, sunburst-chart, sankey-diagram, circle-pack-chart | [treemap-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/treemap-chart.schema.json), [sunburst-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/sunburst-chart.schema.json), [sankey-diagram](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/sankey-diagram.schema.json), [circle-pack-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/circle-pack-chart.schema.json) |
| **Statistical** | box-plot, strip-plot, parallel-coordinates-plot, heat-map | [box-plot](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/box-plot.schema.json), [strip-plot](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/strip-plot.schema.json), [parallel-coordinates-plot](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/parallel-coordinates-plot.schema.json), [heat-map](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/heat-map.schema.json) |
| **Other** | wordcloud-chart, ohlc-chart, image, video, text | [wordcloud-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/wordcloud-chart.schema.json), [ohlc-chart](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/ohlc-chart.schema.json), [image](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/image.schema.json), [video](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/video.schema.json), [text](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/text.schema.json) |

Additional schemas: [slots.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/slots.schema.json), [options.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/options.schema.json), [viz-item-type.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/viz-item-type.schema.json)

**Built-in Themes**: `default`, `default_dark`, `vivid`, `seasonal`, `orion`, `royale`, `urban`, `pinky`, `bliss`, `radiant`, `classic`, `classic_dark`

### Slots (Data Configuration)

Slots define what data appears in a chart. Common slot names:
- `x-axis` / `y-axis`: Dimension columns for categories
- `measure`: Numeric columns with aggregations (sum, count, average, etc.)
- `legend`: Grouping/color dimension
- `category`: Category dimension (donut, funnel, filters)
- `size`: Bubble/symbol sizing

### Filling Slots by Data Type

Each slot content item requires a `type` property that determines how to configure it:

**1. Numeric Data (type: "numeric")** - For measures/values
```javascript
{
  type: 'numeric',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  aggregationFunc: 'sum',  // Required: sum, average, count, distinctcount, min, max, median, stddev, rate, cumulativesum, weightedaverage
  format: '$,.2f',         // Optional: D3 format string
  label: { en: 'Revenue' }
}
```

**2. Categorical Data (type: "hierarchy")** - For dimensions/groupings
```javascript
{
  type: 'hierarchy',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  level: 1,                // Hierarchy level (1 = top level)
  label: { en: 'Category' }
}
```

**3. Datetime Data (type: "datetime")** - For time-based dimensions
```javascript
{
  type: 'datetime',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  level: 3,                // 1=year, 2=quarter, 3=month, 4=week, 5=day, 6=hour, 7=minute, 8=second, 9=millisecond
  datetimeDisplayMode: 'default',  // default, month_name, weekday_name, day_in_month, week_number, etc.
  format: '%Y-%m',         // Optional: D3 time format
  label: { en: 'Date' }
}
```

**4. Mixed Data Scenarios**
- **Numeric as category**: Use `bins` to group numeric values into ranges
  ```javascript
  { type: 'numeric', columnId: '...', datasetId: '...', bins: { enabled: true, number: 10 } }
  ```
- **Hierarchy in measure slot**: Use `aggregationFunc: 'count'` or `'distinctcount'`
  ```javascript
  { type: 'hierarchy', columnId: '...', datasetId: '...', aggregationFunc: 'distinctcount' }
  ```
- **Datetime in measure slot**: Use `aggregationFunc: 'count'` or `'distinctcount'`

For complete slot schemas per chart type, see the dereferenced JSON schemas above

### Component Properties

Key properties for the VizItem component:
- `type`: Chart type identifier
- `slots`: Data slot configuration array
- `options`: Visual customization object
- `filters`: Runtime filter array
- `authKey` / `authToken`: Embed authorization
- `appServer` / `apiHost`: Server endpoints

> **Title Format**: The `title` option must be an object with language keys (e.g., `{ en: 'Title' }`), not a string.

Full Flex reference: https://developer.luzmo.com/guide/flex--introduction

## Dashboard Embedding

Embed complete Luzmo dashboards using the `LuzmoDashboardComponent`:
- Embed full dashboards or individual dashboard items
- Support for embedded dashboard editor
- Customizable loader, language, and timezone settings

## Luzmo IQ (AI Data Assistant)

Luzmo IQ provides AI-powered natural language data exploration:
- `LuzmoIQChatComponent`: Full chat interface for data questions
- `LuzmoIQAnswerComponent`: Display AI-generated chart responses
- Requires IQ license - contact Luzmo for access

Full IQ reference: https://developer.luzmo.com/guide/iq--introduction

## Backend SDKs

| Language | Package | Install |
|----------|---------|---------|
| Node.js | @luzmo/nodejs-sdk | `npm install @luzmo/nodejs-sdk` |
| Python | luzmo-sdk | `pip install luzmo-sdk` |
| PHP | luzmo/luzmo-sdk-php | `composer require luzmo/luzmo-sdk-php` |
| Java | com.luzmo:sdk | Maven: `com.luzmo:sdk` |
| C# | LuzmoSDK | `dotnet add package LuzmoSDK` |

## Frontend SDKs

| Framework | Package | Install |
|-----------|---------|---------|
| Web Components | @luzmo/embed | `npm install @luzmo/embed` |
| React | @luzmo/react-embed | `npm install @luzmo/react-embed` |
| Angular | @luzmo/ngx-embed | `npm install @luzmo/ngx-embed` |
| Vue | @luzmo/vue-embed | `npm install @luzmo/vue-embed` |
| React Native | @luzmo/react-native-embed | `npm install @luzmo/react-native-embed` |

## Quick Links

- Developer Documentation: https://developer.luzmo.com
- API Reference: https://developer.luzmo.com/guide/api--introduction
- Flex SDK Guide: https://developer.luzmo.com/guide/flex--introduction
- Chart Documentation: https://developer.luzmo.com/guide/flex--chart-docs
- OpenAPI Schema: https://developer.luzmo.com/assets/oas/oas-luzmo-full.json
- JSON Schemas (v0.1.97): https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/
- Academy (Tutorials): https://academy.luzmo.com
- Academy AI Search: Use `POST https://ai-knowledge-base.luzmo.com/ask-question` with `{"question": "your query", "stream": true}` for AI-powered answers about Luzmo

## Related Files

- Detailed API: /assets/llm-resources/llms-api.txt
- Detailed Flex: /assets/llm-resources/llms-flex.txt
- Coding Assistant: /assets/llm-resources/AGENTS.md