Superset REST API

Operate Superset via its native REST API. No MCP, no SSH — just HTTP.

Connection

Set the Superset URL before making requests:

SUPERSET_URL=<your-superset-host>

Auth (Always Do First)

curl -s -X POST "$SUPERSET_URL/api/v1/security/login" \
  -H 'Content-Type: application/json' \
  -d '{"username":"<user>","password":"<pass>","provider":"db"}'

Returns {"access_token": "eyJ..."}. Expires in ~15 min. Use in all requests:

Authorization: Bearer <access_token>

Ask the user for credentials if not provided.

Chart Operations

Get Chart

curl -s "$SUPERSET_URL/api/v1/chart/<id>" -H "Authorization: Bearer $TOKEN"

Returns result.params — a JSON string (not object). Parse with json.loads().

Update Chart (Persists Immediately)

curl -s -X PUT "$SUPERSET_URL/api/v1/chart/<id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": "<stringified-json>"}'

params must be a JSON string, not a JSON object. Stringify before sending.

Create Chart

curl -s -X POST "$SUPERSET_URL/api/v1/chart/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slice_name": "Chart Name",
    "datasource_id": <id>,
    "datasource_type": "table",
    "viz_type": "echarts_timeseries_bar",
    "params": "<stringified-json>"
  }'

Dataset Operations

Get Dataset (Check Columns)

curl -s "$SUPERSET_URL/api/v1/dataset/<id>" -H "Authorization: Bearer $TOKEN"

Returns result.columns array with column_name and type.

List Datasets

curl -s "$SUPERSET_URL/api/v1/dataset/?q=(page_size:100)" -H "Authorization: Bearer $TOKEN"

Dashboard Operations

Get Dashboard

curl -s "$SUPERSET_URL/api/v1/dashboard/<id>" -H "Authorization: Bearer $TOKEN"

result.position_json contains chart layout. Chart IDs are in the CHART node meta.chartId.

Chart Params Templates

echarts_timeseries_bar / echarts_timeseries_line

{
  "viz_type": "echarts_timeseries_bar",
  "datasource": "<dataset_id>__table",
  "x_axis": "<column>",
  "metrics": [
    {
      "expressionType": "SIMPLE",
      "column": {"column_name": "<col>"},
      "aggregate": "SUM",
      "label": "Label",
      "optionName": "metric_<col>_<agg>"
    }
  ],
  "adhoc_filters": [
    {
      "expressionType": "SIMPLE",
      "subject": "<column>",
      "operator": "==",
      "comparator": "<value>",
      "clause": "WHERE",
      "filterOptionName": "filter_<name>"
    }
  ],
  "time_range": "No filter",
  "row_limit": 100
}

pie

{
  "viz_type": "pie",
  "datasource": "<dataset_id>__table",
  "metric": {
    "expressionType": "SIMPLE",
    "column": {"column_name": "<col>"},
    "aggregate": "COUNT",
    "label": "Label",
    "optionName": "metric_<name>"
  },
  "groupby": ["<column>"],
  "donut": true
}

big_number_total

{
  "viz_type": "big_number_total",
  "datasource": "<dataset_id>__table",
  "metric": {
    "expressionType": "SIMPLE",
    "column": {"column_name": "<col>"},
    "aggregate": "SUM",
    "label": "Label",
    "optionName": "metric_<name>"
  }
}

table

{
  "viz_type": "table",
  "datasource": "<dataset_id>__table",
  "all_columns": ["<col1>", "<col2>"],
  "order_by_cols": [],
  "row_limit": 1000
}

SQL Expression Metric

{
  "expressionType": "SQL",
  "sqlExpression": "SUM(revenue) / COUNT(DISTINCT customer_id)",
  "label": "Avg Revenue per Customer"
}

metric vs metrics

| viz_type | Field | Type | |----------|-------|------| | pie | metric | Single object | | big_number_total | metric | Single object | | big_number | metric | Single object | | echarts_timeseries_bar | metrics | Array | | echarts_timeseries_line | metrics | Array | | echarts_area | metrics | Array | | mixed_timeseries | metrics | Array | | table | none | - |

Available viz_type (Superset 6.1)

| Use | viz_type | metric field | |-----|----------|-------------| | Bar | echarts_timeseries_bar | metrics | | Line | echarts_timeseries_line | metrics | | Area | echarts_area | metrics | | Scatter | echarts_timeseries_scatter | metrics | | Mixed | mixed_timeseries | metrics | | Pie | pie | metric | | KPI | big_number_total | metric | | KPI + trend | big_number | metric | | Table | table | none | | Pivot | pivot_table_v2 | - | | Heatmap | heatmap_v2 | - | | Treemap | treemap_v2 | - |

Removed (do NOT use): scatter_chart, dist_bar, heatmap, histogram, sankey, sunburst, treemap

Dashboard Layout (position_json)

Requires strict ROOT > GRID > ROW > COLUMN > CHART hierarchy:

{
  "DASHBOARD_VERSION_KEY": "v2",
  "ROOT_ID": {"type": "ROOT", "id": "ROOT_ID", "children": ["GRID_ID"]},
  "GRID_ID": {"type": "GRID", "id": "GRID_ID", "children": ["ROW-1"], "parents": ["ROOT_ID"]},
  "ROW-1": {
    "type": "ROW", "id": "ROW-1",
    "children": ["COLUMN-1"],
    "parents": ["ROOT_ID", "GRID_ID"],
    "meta": {"background": "BACKGROUND_TRANSPARENT"}
  },
  "COLUMN-1": {
    "type": "COLUMN", "id": "COLUMN-1",
    "children": ["CHART-<id>"],
    "parents": ["ROOT_ID", "GRID_ID", "ROW-1"],
    "meta": {"background": "BACKGROUND_TRANSPARENT", "width": 12}
  },
  "CHART-<id>": {
    "type": "CHART", "id": "CHART-<id>",
    "children": [],
    "parents": ["ROOT_ID", "GRID_ID", "ROW-1", "COLUMN-1"],
    "meta": {"chartId": <id>, "height": 50, "width": 12, "sliceName": "Title", "uuid": "<uuid>"}
  }
}

Grid width = 12 columns per row (6 = half, 4 = third)
Every CHART must have COLUMN and ROW parents
Every node must have complete parents chain

Workflow

When user asks to modify a chart:

Auth — get access token
GET chart — read current params
Identify what to change (metrics, filters, columns)
If changing metrics, verify column exists (GET dataset)
Modify params JSON string
PUT chart with updated params
Tell user to refresh dashboard

Additional Resources

For complete API endpoint reference, see reference.md