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

> Automate Superset dashboard and chart management with the REST API. Perform CRUD operations, bulk deletes, YAML exports, and more programmatically.

- Repository: [The Apache Software Foundation/superset](https://github.com/apache/superset)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/apache/superset/blob/main/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`](https://github.com/apache/superset/blob/main/superset/config.py). Two primary classes handle resource management:

* **`DashboardRestApi`** in [`superset/dashboards/api.py`](https://github.com/apache/superset/blob/main/superset/dashboards/api.py) manages dashboard lifecycle operations
* **`ChartRestApi`** in [`superset/charts/api.py`](https://github.com/apache/superset/blob/main/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`](https://github.com/apache/superset/blob/main/superset/initialization/__init__.py)) and inherit common response formatting and validation logic from [`superset/views/base_api.py`](https://github.com/apache/superset/blob/main/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`](https://github.com/apache/superset/blob/main/superset/dashboards/api.py)):

```python
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:

```python
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:

```python
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):

```python
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:

```python
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):

```python
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`](https://github.com/apache/superset/blob/main/superset/utils/screenshots.py) to cache dashboard images:

```python
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`](https://github.com/apache/superset/blob/main/superset/charts/api.py)). The payload requires visualization metadata and datasource references:

```python
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):

```python
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`](https://github.com/apache/superset/blob/main/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.