How to Use the Superset REST API for Programmatic Dashboard and Chart Management

Use Apache Superset’s REST API endpoints at /api/v1/dashboard/ and /api/v1/chart/ to automate the full lifecycle of BI assets, including CRUD operations, bulk deletions, YAML exports, and asynchronous screenshot generation, via standard HTTP requests authenticated through Flask-AppBuilder sessions or JWT tokens.

Apache Superset exposes a fully-featured REST API for programmatic management of dashboards and charts. Built on top of Flask-AppBuilder’s BaseSupersetModelRestApi and registered during application startup in superset/initialization/__init__.py, this API enables DevOps teams and data engineers to deploy analytics at scale without manual UI interaction.

API Architecture and Authentication

Core Structure and Routing

The API follows OpenAPI specifications and uses a consistent /api/v1/ prefix configured in superset/config.py. Two primary classes handle resource management:

• DashboardRestApi in superset/dashboards/api.py manages dashboard lifecycle operations
• ChartRestApi in superset/charts/api.py handles chart definitions and metadata

Both classes are registered with the Flask-AppBuilder instance during initialization (lines 38-55 of superset/initialization/__init__.py) and inherit common response formatting and validation logic from superset/views/base_api.py.

Authentication and Permission Models

All endpoints enforce authentication through the @protect decorator, which validates Flask-AppBuilder session cookies or accepts valid JWT/OAuth2 access tokens via the Authorization: Bearer header. The permission model uses class_permission_name attributes ("Dashboard" or "Chart") mapped to FAB roles (Admin, Alpha, Gamma) with method_permission_name restrictions on individual endpoints. Request bodies are validated against Marshmallow schemas such as DashboardPostSchema and ChartPostSchema before processing.

Managing Dashboards Programmatically

Listing and Retrieving Dashboards

To fetch dashboard definitions, send a GET request to the base endpoint. This invokes DashboardRestApi.get_list() (lines 68-95 of superset/dashboards/api.py):

import requests

session = requests.Session()

# Authenticate first (see Authentication section)

resp = session.get("http://localhost:8088/api/v1/dashboard/")
dashboards = resp.json()["result"]
print(f"Found {len(dashboards)} dashboards")

Creating and Updating Dashboards

Create new dashboards by sending a JSON payload matching the DashboardPostSchema. The post() method (lines 83-111) handles creation:

new_dashboard = {
    "dashboard_title": "Sales Overview",
    "slug": "sales-overview",
    "published": True,
    "owners": [1],  # User IDs

}
resp = session.post("http://localhost:8088/api/v1/dashboard/", json=new_dashboard)
dashboard_id = resp.json()["id"]

Update existing dashboards using put() (lines 124-152), which accepts partial updates:

updates = {
    "dashboard_title": "Updated Sales Overview",
    "json_metadata": {"native_filter_configuration": []},
}
resp = session.put(f"http://localhost:8088/api/v1/dashboard/{dashboard_id}", json=updates)

Deleting Single and Multiple Dashboards

Delete individual dashboards via the delete() method (lines 176-190):

resp = session.delete(f"http://localhost:8088/api/v1/dashboard/{dashboard_id}")
print(resp.json()["message"])

For bulk deletions, use Rison encoding to pass multiple IDs to the bulk_delete() method (lines 200-226). The @rison(get_delete_ids_schema) decorator parses the query parameter:

import json
import urllib.parse

ids_to_delete = [10, 11, 12]
rison_query = urllib.parse.quote(json.dumps(ids_to_delete), safe="")
resp = session.delete(f"http://localhost:8088/api/v1/dashboard/?q={rison_query}")

Exporting Dashboards and Generating Screenshots

Export dashboard definitions as ZIP bundles containing YAML files using the export() method (lines 191-221):

resp = session.get(f"http://localhost:8088/api/v1/dashboard/{dashboard_id}/export/")
with open("dashboard_export.zip", "wb") as f:
    f.write(resp.content)

For visual assets, the screenshot() method (lines 262-314) triggers asynchronous Celery tasks defined in superset/utils/screenshots.py to cache dashboard images:

resp = session.get(f"http://localhost:8088/api/v1/dashboard/{dashboard_id}/screenshot/")
data = resp.json()
print(f"Cache key: {data['cache_key']}")

# Fetch the actual image

img_resp = session.get(data["image_url"])
with open("dashboard.png", "wb") as f:
    f.write(img_resp.content)

Managing Charts via the REST API

Creating Chart Definitions

Charts are managed through /api/v1/chart/ with ChartRestApi.post() (lines 125-158 in superset/charts/api.py). The payload requires visualization metadata and datasource references:

new_chart = {
    "slice_name": "Revenue by Region",
    "viz_type": "pie",
    "datasource_id": 5,
    "datasource_type": "table",
    "params": {"groupby": ["region"], "metric": "sum__revenue"},
}
resp = session.post("http://localhost:8088/api/v1/chart/", json=new_chart)
chart_id = resp.json()["id"]

Retrieving Dashboard-Chart Relationships

Fetch all charts associated with a specific dashboard using the relationship endpoint implemented in DashboardRestApi.get_charts() (lines 135-143):

resp = session.get(f"http://localhost:8088/api/v1/dashboard/{dashboard_id}/charts")
charts = resp.json()["result"]
chart_names = [c["slice_name"] for c in charts]

Summary

• Superset’s REST API provides complete programmatic access to dashboards and charts through Flask-AppBuilder endpoints at /api/v1/dashboard/ and /api/v1/chart/
• Authentication supports session cookies or JWT tokens, with permissions enforced via the @protect decorator and FAB role mappings
• Bulk operations use Rison encoding for efficient deletion of multiple resources via query parameters
• Export functionality generates ZIP archives of YAML definitions suitable for version control and migration
• Screenshot generation leverages asynchronous Celery tasks to cache dashboard and chart images

Frequently Asked Questions

How do I authenticate with the Superset REST API programmatically?

Authenticate by establishing a session through the /login/ endpoint with valid credentials, which sets the required Flask-AppBuilder session cookies. For JWT-based access, obtain a bearer token from the login view and include it in the Authorization header. The @protect decorator on all API endpoints validates these authentication mechanisms before processing requests.

Can I perform bulk operations on multiple dashboards at once?

Yes. The API supports bulk deletion through the bulk_delete() method in superset/dashboards/api.py by passing Rison-encoded arrays of IDs via the q query parameter. This allows you to delete multiple dashboards in a single HTTP request rather than iterating through individual DELETE calls.

What formats are supported for exporting dashboards and charts?

The export() methods in both DashboardRestApi and ChartRestApi generate ZIP archives containing YAML files that represent the complete object definitions, including metadata, configurations, and relationships. These bundles can be re-imported into other Superset instances using the corresponding /import/ endpoints.

How do I handle asynchronous screenshot generation for dashboards?

Dashboard screenshots are generated asynchronously via Celery workers. When you call the screenshot endpoint, the API returns a cache key and image URL immediately, but the image may return a 202 status if processing is incomplete. Poll the provided image_url until the task status indicates completion, then download the PNG content from the cached location.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}