core

Luzmo Core

Entry-point for all Luzmo integrations. Establishes security and API patterns that other Luzmo skills assume.

Doc Retrieval

• Fetch the exact developer.luzmo.com/*.md page(s) before coding.
• If it is an index/overview, follow the relevant links to the concrete API, component, chart, schema, or example page.
• Use https://developer.luzmo.com/llms.txt / https://developer.luzmo.com/llms-full.txt only to discover pages, not as the final source.

🚨 CRITICAL RULES 🚨

Read these BEFORE implementing anything with Luzmo:

Security Checkpoint (Hard Stop)

BEFORE generating ANY code, verify:

• API credentials (LUZMO_API_KEY, LUZMO_API_TOKEN) are server-side ONLY
• Embed tokens are generated server-side
• Embed token's id and token properties are passed to frontend (as authKey/authToken)

If ANY checkbox is unchecked, STOP and fix before proceeding.

❌ NEVER ACCEPTABLE:

// Client-side code with credentials - SECURITY BREACH
const client = new Luzmo({
  api_key: 'YOUR_API_KEY',      // EXPOSED!
  api_token: 'YOUR_API_TOKEN'   // EXPOSED!
})

✅ CORRECT PATTERN:

// Server-side: generate token
const embedToken = await client.create('authorization', {...})

// Client-side: use only the token
<luzmo-embed-dashboard 
  authKey={embedToken.id} 
  authToken={embedToken.token} 
/>

Multi-Tenant Data Isolation (Hard Stop — Route, Don't Implement)

If the user needs each tenant/customer to see only their own rows in a shared dataset (row-level / data-level isolation), STOP. Do not build the filter pattern from core.

• This is multitenancy skill territory.
• You may briefly name parameter_overrides and EmbedFilterGroup as the relevant concepts, then route to multitenancy for the full implementation.
• NOTE: user-pool scoping via suborganization (who can see whom) IS a core topic — answer that here.

API Architecture (Critical Difference from REST)

The Luzmo API does NOT use traditional REST HTTP verbs.

   Traditional REST                       Luzmo API
   ─────────────────                      ───────────────────────
   GET    /dashboards/:id        ─►       POST /securable
   PUT    /dashboards/:id        ─►         { action: "get"   ... }
   PATCH  /dashboards/:id        ─►         { action: "update"... }
   DELETE /dashboards/:id        ─►         { action: "delete"... }
                                            { action: "create"... }
                                            { action: "associate"... }
   Method = verb                          Method = POST (always)
   Path   = resource             ─►       Path   = /:resource
   Body   = data                          Body   = { action, key, token, ...params }

❌ Never use: GET, PUT, PATCH, DELETE
✅ Always use: POST with action field in request body

Always cite the API overview when explaining request shapes: https://developer.luzmo.com/guide/api--overview.md

Request structure:

{
  key: API_KEY,
  token: API_TOKEN,
  version: "0.1.0",
  action: "get",  // or "create", "update", "delete", "associate", "dissociate"
  ...params
}

Common mistake: Using action: "search" → Use action: "get" instead

Frontend API Calls with Embed Tokens

While API keys/tokens must stay server-side, embed tokens can make limited frontend API calls based on the token's access scope:

• The embed key/token pair (authKey/authToken) replaces API credentials for these scoped operations — each call only sees what the token's access and filters allow
• This is legitimate and documented behavior — not a security violation like exposing raw API keys
• Commonly used embed-token-accessible APIs:
  • createData / getData — query data from accessible datasets
  • securable — list dashboards/datasets the token has access to
  • aiprompt — IQ natural language queries via /aiprompt (respects token's dataset scope and tenant filters); persisted turns live in aimessage / aiconversation / aimessageasset
  • column — column metadata for datasets in scope
  • formula — formulas for datasets in scope
  • theme — theme retrieval

Security boundary: The embed token's role and access properties determine what frontend calls are allowed. Viewers cannot create/delete resources; designers/owners have broader permissions.

SDK Selection

• Backend (server-side ONLY): @luzmo/nodejs-sdk, luzmo-sdk (Python), luzmo/luzmo-sdk-php, com.luzmo:sdk (Java), LuzmoSDK (C#)
• Frontend (with embed tokens): @luzmo/react-embed, @luzmo/ngx-embed (Angular), @luzmo/vue-embed, @luzmo/embed
• Never mix: Don't use backend SDK in browser or frontend SDK on server

For detailed SDK installation and initialization: See references/sdk-setup.md

API Implementation Patterns

Valid Actions

The action "search" does NOT exist. Use action: "get" instead.

Valid actions:

• create - Create a new resource
• get - Retrieve/search for resources (commonly confused with "search")
• update - Modify an existing resource
• delete - Remove a resource
• associate - Link resources together
• dissociate - Unlink resources

For detailed action shapes and examples: See references/api-actions.md

Using SDKs (Recommended)

Official SDKs abstract the POST-only pattern:

// Node.js SDK
await client.create('securable', { type: 'dashboard', ...properties })
await client.get('securable', { find: { where: { type: 'dashboard' } } })
await client.update('securable', dashboardId, properties)
await client.delete('securable', dashboardId)

API Documentation Patterns

When working with any Luzmo API resource, fetch the documentation before implementation. Do not rely on cached knowledge — always get the latest documentation directly from developer.luzmo.com.

URL Pattern: https://developer.luzmo.com/api/{action}{Resource}.md

Examples:

• Authorization: https://developer.luzmo.com/api/createAuthorization.md
• Dashboard operations: https://developer.luzmo.com/api/createDashboard.md, https://developer.luzmo.com/api/searchDashboard.md, https://developer.luzmo.com/api/updateDashboard.md, https://developer.luzmo.com/api/deleteDashboard.md
• Dataset operations: https://developer.luzmo.com/api/createDataset.md, https://developer.luzmo.com/api/searchDataset.md
• Data queries: https://developer.luzmo.com/api/createData.md
• Themes: https://developer.luzmo.com/api/createTheme.md, https://developer.luzmo.com/api/searchTheme.md

Full API overview: https://developer.luzmo.com/guide/api--overview.md

Frontend component API references:

Component	API Reference URL
Dashboard	https://developer.luzmo.com/guide/embedding--component-api-reference.md
Flex	https://developer.luzmo.com/guide/flex--component-api-reference.md
IQ Chat	https://developer.luzmo.com/guide/iq--chat-component-api.md
IQ Answer	https://developer.luzmo.com/guide/iq--answer-component-api.md

IMPORTANT: When you fetch a doc, also follow up on any additional resources it references inline. Luzmo docs frequently link to related guides (e.g. chart-specific options, plugin endpoints, theme schemas) — read those too before generating code, so the implementation stays grounded in the latest documented shapes.

Documentation Discovery Fallback

When you're uncertain which specific documentation page to fetch:

1. Fetch the developer documentation index at https://developer.luzmo.com/llms.txt (concise) or https://developer.luzmo.com/llms-full.txt (comprehensive with descriptions)
2. Review the index to find relevant pages by description or topic
3. Fetch the specific .md pages you need
4. If those pages are indexes or overviews, follow the relevant links to the concrete implementation docs

You may also reference https://developer.luzmo.com/AGENTS.md for high-level integration patterns, but the detailed documentation lives in the individual .md files listed in the index.

Note on documentation URLs: Pages at developer.luzmo.com are available with a .md suffix for markdown format. Always prefer fetching the .md version when available.

Note on search{Resource} naming: Documentation URLs like https://developer.luzmo.com/api/searchDashboard.md or https://developer.luzmo.com/api/searchDataset.md describe "search/list" operations, but the actual HTTP request body uses "action": "get" (not "action": "search" which doesn't exist). The "search" in the URL is a documentation convention only.

API Base URLs and Version

Depending on your Luzmo tenancy, use the correct base URL:

Region	API Base URL
EU (default)	https://api.luzmo.com/0.1.0
US	https://api.us.luzmo.com/0.1.0
VPC	https://{vpc}-api.luzmo.com/0.1.0 (or custom CNAME)

Note: The version /0.1.0 is part of the URL path.

Including Associated Models

When retrieving resources, you can include related models using the include parameter:

{
  action: "get",
  find: {
    where: { id: "..." }
  },
  include: [
    { model: 'Column' },
    { model: 'Account' }
  ]
}

Response property naming: Included models are returned as lowercase plural properties:

Included Model	Response Property
Column	columns
Securable	securables
User	users
Account	accounts

Example response:

{
  data: [{
    id: "...",
    name: "My Dataset",
    columns: [...],  // Not "Columns"
    accounts: [...]  // Not "Account" or "Accounts"
  }]
}

Environment Variables

Standard naming conventions for Luzmo credentials and configuration:

Server-side only (NEVER in client code):

LUZMO_API_KEY=<your-api-key>
LUZMO_API_TOKEN=<your-api-token>

Used in both server-side and client-side:

LUZMO_API_HOST=https://api.luzmo.com
LUZMO_APP_SERVER=https://app.luzmo.com

Default values by region:

EU (default):

• API: https://api.luzmo.com
• App: https://app.luzmo.com

US:

• API: https://api.us.luzmo.com
• App: https://app.us.luzmo.com

VPC:

• API: https://{vpc}-api.luzmo.com (or custom CNAME)
• App: https://{vpc}-app.luzmo.com (or custom CNAME)

Embed Authorization Tokens

The createAuthorization API generates short-lived tokens for frontend access:

Response format:

{
  id: "<embed-key>",     // Pass as authKey to frontend
  token: "<embed-token>" // Pass as authToken to frontend
}

Important properties:

Required:

• type — always "embed" for end-user embed tokens
• username — stable, unique identifier for the user (immutable; don't use email if it can change)
• name — display name shown in the Luzmo UI
• email — used for Luzmo UI features (e.g. alert email prefill)
• access — which collections, dashboards, or datasets the token can access

Commonly used optional:

• suborganization — tenant context; determines which other users this user can see/interact with
• role — "viewer" (default), "designer", or "owner"
• expiry — RFC 3339 timestamp; defaults to 24 h, max 1 year
• parameter_overrides — supply tenant-specific values for parameterized dataset filters (for full row-level tenant isolation, defer to multitenancy — do not assemble the complete filter pattern from core)
• account_overrides — override database/plugin connection credentials per tenant (for full row-level tenant isolation, defer to multitenancy — do not assemble the complete filter pattern from core)
• iq.context — custom system prompt appended to IQ queries for this token
• environment — pin to "production", "development", "acceptance", "qa", or null (latest)

For the full property list see https://developer.luzmo.com/api/createAuthorization.md.

See references/authorization-patterns.md for detailed examples of all properties.

Backend SDKs (Server-Side Only)

Install the latest version of the appropriate SDK for your language. Never use these in client-side code.

Language	Package
Node.js	@luzmo/nodejs-sdk
Python	luzmo-sdk
PHP	luzmo/luzmo-sdk-php
Java	com.luzmo:sdk
C#	LuzmoSDK

Frontend SDKs (Client-Side with Embed Tokens)

These SDKs use embed tokens (authKey/authToken), never API credentials.

Framework	Package
Web Components	@luzmo/embed
React	@luzmo/react-embed
Angular	@luzmo/ngx-embed
Vue	@luzmo/vue-embed
React Native	@luzmo/react-native-embed †

† Dashboard/Flex embedding only — IQ Chat/Answer components require a web browser (see ai-analytics).

Embedding a Saved Dashboard or Chart by ID

Use this path when the user wants to display an existing Luzmo dashboard or chart that was already created and saved in Luzmo — identified by dashboardId (or dashboardSlug). This is the most common embedding scenario.

Component Names (Framework-Specific)

Framework	Dashboard
Vanilla JS	<luzmo-embed-dashboard>
React	LuzmoDashboardComponent
Angular / Vue	<luzmo-dashboard>

❌ WRONG: <cumul-dashboard> (deprecated)
✅ CORRECT: <luzmo-embed-dashboard> (vanilla JS)

Minimal Required Props

appServer, apiHost, authKey, authToken, dashboardId

Use dashboardSlug instead of dashboardId when the dashboard has a slug configured.

Sizing

Dashboards have variable height based on content. Width fills the container automatically.

• If you need bounded height, add overflow-y: auto to the container
• If the dashboard is not filling width, check for largeScreen screen mode in the dashboard settings

<div style="height: 600px; overflow-y: auto;">
  <luzmo-embed-dashboard ...></luzmo-embed-dashboard>
</div>

Custom Charts in Dashboards

An embedded dashboard renders whatever chart types it contains — including any org-released custom chart — with no special handling. Custom charts are built separately (see custom-charts); once released org-wide, they behave like any other chart type inside a dashboard.

editMode (View vs Edit)

Token role controls whether edit mode can activate:

Role	Capability
viewer	View only — cannot activate edit mode
designer	Edit charts and layout
owner	Same as designer + can favorite a dashboard variant on behalf of other users

For self-service editing (Embedded Dashboard Editor or ACK), see analytics-studio. For deeper dashboard component API, events, and editMode values, see references/dashboard-embedding.md.

Bundled References

For deeper, focused guidance, read these files only when relevant:

• references/sdk-setup.md — Per-language backend SDK install + per-framework frontend SDK install, with code samples
• references/authorization-patterns.md — Common createAuthorization shapes (viewer, designer, suborganization, theme/css, expiry, advanced properties). Multi-tenant isolation is covered only by multitenancy.
• references/api-actions.md — Full reference for the POST + action model, including include/pagination shapes and lowercase-plural response naming
• references/typescript-examples.md — Type-safe TypeScript interfaces for authorization tokens, slot configs, and API responses
• references/common-mistakes.md — Detailed anti-patterns with error messages, root causes, and fixes
• references/dashboard-embedding.md — Saved dashboard/chart embedding by id. Covers component setup, dashboardId vs dashboardSlug, sizing, editMode, roles, events, and runtime control.
• references/local-development-proxy.md — Localhost CORS/realtime recipe for Flex, web-component dashboards, and IQ-rendered charts. Covers same-origin proxying for /0.1.0 and /realtime, and why appServer must stay pointed at the Luzmo app host.

Implementation Documentation

Fetch these for specific implementation details (and any guides they reference inline):

• Authentication and embed tokens:
  https://developer.luzmo.com/guide/dashboard-embedding--generating-an-authorization-token.md
• Authorization API:
  https://developer.luzmo.com/api/createAuthorization.md
• Core API overview:
  https://developer.luzmo.com/guide/api--overview.md
• Basic frontend embedding:
  https://developer.luzmo.com/guide/dashboard-embedding--embed-into-application.md

Hand Off

When to escalate to other skills:

• WHEN the user wants to build Flex charts in code → use data-visualization
• WHEN the user needs to build a brand-new custom chart component (no built-in type fits) → use custom-charts
• WHEN the user wants end-users to edit/build charts (ACK, editor) → use analytics-studio
• WHEN the user mentions tenants, customers, isolation, or row-level security → use multitenancy (SECURITY CRITICAL)
• WHEN the user needs to connect a database/file/API or push data → use data-integration
• WHEN the user wants to apply themes, brand colors, or CSS → use theming
• WHEN the user wants AI/natural-language data Q&A → use ai-analytics
• WHEN the user needs CRUD/search/delete scripts against the API → use resource-management
• WHEN the user reports a bug, error, or "not working" symptom → use troubleshooting FIRST

This skill does NOT cover:

• Building Flex charts in code — slots/options, sizing, contextId (use data-visualization)
• Building a brand-new custom chart component — manifest, render/resize/buildQuery, org release (use custom-charts)
• Multi-tenant filter implementation details (use multitenancy)
• Data ingestion or dataset modeling (use data-integration)

Common Mistakes

Luzmo's API architecture differs from typical REST APIs. The most common mistakes involve authentication security, HTTP verbs, and action naming.

For detailed error patterns with symptoms and fixes, see references/common-mistakes.md.

Quick reference of top issues:

• Using GET/PUT/DELETE instead of POST with action field (⚠️ VERY COMMON)
• Using action: "search" instead of action: "get" (⚠️ VERY COMMON)
• Exposing API credentials in client-side code (⚠️ COMMON - SECURITY CRITICAL)
• Wrong property names for included models (⚠️ COMMON)

Avoid

• Giving frontend examples that use API keys directly
• Using REST-style HTTP verbs (GET, PUT, PATCH, DELETE) with the Luzmo API
• Using action: "search" instead of action: "get"
• Inventing unsupported API shapes without fetching documentation

Canonical Sources

• Index: https://developer.luzmo.com/llms.txt, https://developer.luzmo.com/llms-full.txt
• API: https://developer.luzmo.com/api/{action}{Resource}.md
• Guides: https://developer.luzmo.com/guide/*.md
• Flex charts: https://developer.luzmo.com/flex/charts/{type}.md

If content exists on developer.luzmo.com, link — do not duplicate specs here.