5.1 Using the API | Advanced topics for developers

In addition to the visual renderer, Luminon exposes local endpoints you can query from the terminal. For local development, the renderer runs at ` http://localhost:5173` and the remote HTTP MCP runs at ` http://localhost:3001/mcp`.

luminon start
luminon start remote

With the local renderer you can list dashboards and datasets with `curl`. This is useful for quick inspection, tests, or small scripts.

curl -sS http://localhost:5173/api/dashboards

{"dashboards":[{"id":"db_demo_coffee","name":"Coffee Roastery Lab","subtitle":"A simple filter-free sandbox for trying chart layouts and themes.","themePreset":"pastel","presentation":{"numberFormat":"compact","decimals":1},"charts":[{"id":"coffee_revenue_combo","type":"combo","title":"Revenue and Subscription Orders by Period","datasetId":"coffee_roastery_lab","data":[],"x":"period","barY":"revenue","lineY":"subscription_orders","source":{"datasetId":"coffee_roastery_lab","aggregation":"sum","xField":"period","barField":"revenue","lineField":"subscription_orders"}},{"id":"coffee_roast_mix","type":"donut","title":"Revenue Share by Roast Profile","datasetId":"coffee_roastery_lab","data":[],"source":{"datasetId":"coffee_roastery_lab","aggregation":"sum","categoryField":"roast_profile","valueField":"revenue"}},{"id":"coffee_origin_radar", ...]}

curl -sS http://localhost:5173/api/datasets

{"datasets":[{"id":"coffee_roastery_lab","name":"coffee_roastery_lab","columns":["year","month","period","blend","origin","roast_profile","bags_sold","subscription_orders","revenue","cup_score"],"rows":[{"year":2025,"month":"Dec","period":"2025-12","blend":"Aurora Blend","origin":"Ethiopia","roast_profile":"Light","bags_sold":315,"subscription_orders":58,"revenue":8298,"cup_score":87.7},{"year":2025,"month":"Dec","period":"2025-12","blend":"Summit Espresso","origin":"Colombia","roast_profile":"Medium","bags_sold":346,"subscription_orders":60,"revenue":8165,"cup_score":87},{"year":2025,"month":"Dec","period":"2025-12","blend":"Night Shift","origin":"Kenya","roast_profile":"Espresso","bags_sold":263,"subscription_orders":45,"revenue":7497,"cup_score":88.2} ...]}

If you need to query a specific dashboard by `id`, `GET /api/dashboards/:id` returns the requested dashboard directly. The `Share` flow is still separate and is used to create shared or passcode-protected links.

If you want to call tools directly, use the remote HTTP MCP at ` http://localhost:3001/mcp`. That endpoint only exists if you also started `luminon start remote`.

If the response is `{"error":"Unauthorized"}`, you need to send a Bearer token. You can generate one with `luminon token create` and check the active token with `luminon token current`. MCP tools expect `params.arguments.input`, even when the input is empty.

luminon token create my-api-token
luminon token current

curl -sS -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_dashboards",
      "arguments": {
        "input": {}
      }
    }
  }'

id | name | charts | timestamp | status ------------------|-----------------------------------|--------|--------------------------|------- db_demo_coffee | Coffee Roastery Lab | 4 | 2026-03-26T00:00:00.000Z | active db_demo_hr | HR Workforce Overview | 8 | 2026-03-26T00:00:00.000Z | active db_demo_sales | Sales Performance Hub | 9 | 2026-03-26T00:00:00.000Z | active db_demo_marketing | Marketing Campaign Command Center | 9 | 2026-03-26T00:00:00.000Z | active db_sxq7cz45 | Coffee Workforce Overview v2 | 4 | 2026-05-20T16:31:33.466Z | active db_8no6qqcf | Coffee Workforce Overview v3 | 4 | 2026-05-20T16:47:28.148Z | active db_415r1aw8 | Coffee Workforce Overview v4 | 4 | 2026-05-20T16:50:57.942Z | active db_m7bcfias | Coffee Workforce Overview v5 | 4 | 2026-05-20T16:56:22.594Z | active db_2y53y6m5 | Template Test Dashboard | 0 | 2026-06-03T22:26:01.992Z | active db_mxp4qvum | Delete Chart Smoke V2 | 0 | 2026-06-03T22:27:22.460Z | active db_gxclrszt | Retail Analytics Overview | 4 | 2026-06-06T17:14:22.592Z | active

curl -sS -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_datasets",
      "arguments": {
        "input": {}
      }
    }
  }'

id | name | rows | columns | readOnly | updatedAt -------------------------------|--------------------------------|------|---------|----------|------------------------- coffee_roastery_lab | coffee_roastery_lab | 48 | 10 | no | 2026-03-26T00:00:00.000Z hr_dataset | HR_dataset | 30 | 16 | no | 2026-03-26T00:00:00.000Z sales_complex | Sales Complex | 1152 | 9 | no | 2026-03-26T00:00:00.000Z marketing_campaign_performance | marketing_campaign_performance | 288 | 18 | no | 2026-03-26T00:00:00.000Z retail-analytics | Retail Analytics | 1 | 21 | no | 2026-06-02T21:44:14.349Z retail-analytics-monthly | Retail Analytics Monthly | 12 | 2 | no | 2026-06-02T21:11:23.193Z ds_sgo6cmlj | Retail Analytics | 152 | 21 | no | 2026-06-06T17:14:18.789Z default_business | Default business dataset | 18 | 7 | yes | 2025-03-01T00:00:00.000Z

curl -sS -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list_dataset_content",
      "arguments": {
        "input": {
          "datasetId": "coffee_roastery_lab"
        }
      }
    }
  }'

year | month | period | blend | origin | roast_profile | bags_sold | subscription_orders | revenue | cup_score -----|-------|---------|-----------------|-----------|---------------|-----------|---------------------|---------|---------- 2025 | Dec | 2025-12 | Aurora Blend | Ethiopia | Light | 315 | 58 | 8298 | 87.7 2025 | Dec | 2025-12 | Summit Espresso | Colombia | Medium | 346 | 60 | 8165 | 87 2025 | Dec | 2025-12 | Night Shift | Kenya | Espresso | 263 | 45 | 7497 | 88.2 2025 | Dec | 2025-12 | Harbor Decaf | Guatemala | Dark | 236 | 41 | 5278 | 84.9 2025 | Nov | 2025-11 | Night Shift | Kenya | Espresso | 262 | 49 | 7580 | 88.8 2025 | Nov | 2025-11 | Aurora Blend | Ethiopia | Light | 281 | 57 | 7531 | 88 2025 | Nov | 2025-11 | Summit Espresso | Colombia | Medium | 309 | 58 | 7389 | 86.5 2025 | Nov | 2025-11 | Harbor Decaf | Guatemala | Dark | 211 | 40 | 4789 | 84.5 2025 | Oct | 2025-10 | Night Shift | Kenya | Espresso | 241 | 48 | 7051 | 88.2 2025 | Oct | 2025-10 | Aurora Blend | Ethiopia | Light | 259 | 55 | 7002 | 87.6 2025 | Oct | 2025-10 | Summit Espresso | Colombia | Medium | 284 | 57 | 6873 | 86.9 2025 | Oct | 2025-10 | Harbor Decaf | Guatemala | Dark | 194 | 39 | 4449 | 84.8 2025 | Sep | 2025-09 | Night Shift | Kenya | Espresso | 231 | 47 | 6785 | 88.2 2025 | Sep | 2025-09 | Aurora Blend | Ethiopia | Light | 248 | 55 | 6762 | 87.7 2025 | Sep | 2025-09 | Summit Espresso | Colombia | Medium | 272 | 56 | 6614 | 87 2025 | Sep | 2025-09 | Harbor Decaf | Guatemala | Dark | 186 | 38 | 4279 | 84.5 2025 | Aug | 2025-08 | Night Shift | Kenya | Espresso | 215 | 46 | 6375 | 88.8 2025 | Aug | 2025-08 | Aurora Blend | Ethiopia | Light | 230 | 53 | 6320 | 88 2025 | Aug | 2025-08 | Summit Espresso | Colombia | Medium | 253 | 55 | 6216 | 86.5 2025 | Aug | 2025-08 | Harbor Decaf | Guatemala | Dark | 173 | 37 | 4014 | 84.8 Rows: 20/48 (truncated)

Other useful examples you can add to this section are `describe_dataset` to inspect the schema, `list_dashboard_versions` to review snapshots, `update_dataset` to replace or append rows, and `update_dashboard_filters` to automate global filters.

`describe_dataset` is useful when you want to inspect columns and a short preview of the dataset. `list_dataset_content` is better when you want to review real rows in a table, for example to validate data or compare changes after an update.