Back to Superset

API Reference

docs/developer_docs/api.mdx

2021.41.042.4 KB
Original Source

import { Alert } from 'antd';

REST API Reference

Superset exposes a comprehensive REST API that follows the OpenAPI specification. You can use this API to programmatically interact with Superset for automation, integrations, and custom applications.

<Alert type="info" showIcon message="Code Samples & Schema Documentation" description={ <span> Each endpoint includes ready-to-use code samples in <strong>cURL</strong>, <strong>Python</strong>, and <strong>JavaScript</strong>. The sidebar includes <strong>Schema definitions</strong> for detailed data model documentation. </span> } style={{ marginBottom: '24px' }} />


Authentication

Most API endpoints require authentication via JWT tokens.

Quick Start

bash
# 1. Get a JWT token
curl -X POST http://localhost:8088/api/v1/security/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin", "provider": "db"}'

# 2. Use the access_token from the response
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://localhost:8088/api/v1/dashboard/

Security Endpoints

MethodEndpointDescription
GETGet the CSRF token/api/v1/security/csrf_token/
POSTGet a guest token/api/v1/security/guest_token/
POSTCreate security login/api/v1/security/login
POSTCreate security refresh/api/v1/security/refresh

API Endpoints

Core Resources

<details> <summary><strong>Dashboards</strong> (26 endpoints) — Create, read, update, and delete dashboards.</summary>
MethodEndpointDescription
DELETEBulk delete dashboards/api/v1/dashboard/
GETGet a list of dashboards/api/v1/dashboard/
POSTCreate a new dashboard/api/v1/dashboard/
GETGet metadata information about this API resource (dashboard--info)/api/v1/dashboard/_info
GETGet a dashboard detail information/api/v1/dashboard/{id_or_slug}
GETGet a dashboard's chart definitions./api/v1/dashboard/{id_or_slug}/charts
POSTCreate a copy of an existing dashboard/api/v1/dashboard/{id_or_slug}/copy/
GETGet dashboard's datasets/api/v1/dashboard/{id_or_slug}/datasets
DELETEDelete a dashboard's embedded configuration/api/v1/dashboard/{id_or_slug}/embedded
GETGet the dashboard's embedded configuration/api/v1/dashboard/{id_or_slug}/embedded
POSTSet a dashboard's embedded configuration/api/v1/dashboard/{id_or_slug}/embedded
PUTUpdate dashboard by id_or_slug embedded/api/v1/dashboard/{id_or_slug}/embedded
GETGet dashboard's tabs/api/v1/dashboard/{id_or_slug}/tabs
DELETEDelete a dashboard/api/v1/dashboard/{pk}
PUTUpdate a dashboard/api/v1/dashboard/{pk}
POSTCompute and cache a screenshot (dashboard-pk-cache-dashboard-screenshot)/api/v1/dashboard/{pk}/cache_dashboard_screenshot/
PUTUpdate colors configuration for a dashboard./api/v1/dashboard/{pk}/colors
DELETERemove the dashboard from the user favorite list/api/v1/dashboard/{pk}/favorites/
POSTMark the dashboard as favorite for the current user/api/v1/dashboard/{pk}/favorites/
PUTUpdate native filters configuration for a dashboard./api/v1/dashboard/{pk}/filters
GETGet a computed screenshot from cache (dashboard-pk-screenshot-digest)/api/v1/dashboard/{pk}/screenshot/{digest}/
GETGet dashboard's thumbnail/api/v1/dashboard/{pk}/thumbnail/{digest}/
GETDownload multiple dashboards as YAML files/api/v1/dashboard/export/
GETCheck favorited dashboards for current user/api/v1/dashboard/favorite_status/
POSTImport dashboard(s) with associated charts/datasets/databases/api/v1/dashboard/import/
GETGet related fields data (dashboard-related-column-name)/api/v1/dashboard/related/{column_name}
</details> <details> <summary><strong>Charts</strong> (20 endpoints) — Create, read, update, and delete charts (slices).</summary>
MethodEndpointDescription
DELETEBulk delete charts/api/v1/chart/
GETGet a list of charts/api/v1/chart/
POSTCreate a new chart/api/v1/chart/
GETGet metadata information about this API resource (chart--info)/api/v1/chart/_info
DELETEDelete a chart/api/v1/chart/{pk}
GETGet a chart detail information/api/v1/chart/{pk}
PUTUpdate a chart/api/v1/chart/{pk}
GETCompute and cache a screenshot (chart-pk-cache-screenshot)/api/v1/chart/{pk}/cache_screenshot/
GETReturn payload data response for a chart/api/v1/chart/{pk}/data/
DELETERemove the chart from the user favorite list/api/v1/chart/{pk}/favorites/
POSTMark the chart as favorite for the current user/api/v1/chart/{pk}/favorites/
GETGet a computed screenshot from cache (chart-pk-screenshot-digest)/api/v1/chart/{pk}/screenshot/{digest}/
GETGet chart thumbnail/api/v1/chart/{pk}/thumbnail/{digest}/
POSTReturn payload data response for the given query (chart-data)/api/v1/chart/data
GETReturn payload data response for the given query (chart-data-cache-key)/api/v1/chart/data/{cache_key}
GETDownload multiple charts as YAML files/api/v1/chart/export/
GETCheck favorited charts for current user/api/v1/chart/favorite_status/
POSTImport chart(s) with associated datasets and databases/api/v1/chart/import/
GETGet related fields data (chart-related-column-name)/api/v1/chart/related/{column_name}
PUTWarm up the cache for the chart/api/v1/chart/warm_up_cache
</details> <details> <summary><strong>Datasets</strong> (18 endpoints) — Manage datasets (tables) used for building charts.</summary>
MethodEndpointDescription
DELETEBulk delete datasets/api/v1/dataset/
GETGet a list of datasets/api/v1/dataset/
POSTCreate a new dataset/api/v1/dataset/
GETGet metadata information about this API resource (dataset--info)/api/v1/dataset/_info
DELETEDelete a dataset/api/v1/dataset/{pk}
GETGet a dataset/api/v1/dataset/{pk}
PUTUpdate a dataset/api/v1/dataset/{pk}
DELETEDelete a dataset column/api/v1/dataset/{pk}/column/{column_id}
DELETEDelete a dataset metric/api/v1/dataset/{pk}/metric/{metric_id}
PUTRefresh and update columns of a dataset/api/v1/dataset/{pk}/refresh
GETGet charts and dashboards count associated to a dataset/api/v1/dataset/{pk}/related_objects
GETGet distinct values from field data (dataset-distinct-column-name)/api/v1/dataset/distinct/{column_name}
POSTDuplicate a dataset/api/v1/dataset/duplicate
GETDownload multiple datasets as YAML files/api/v1/dataset/export/
POSTRetrieve a table by name, or create it if it does not exist/api/v1/dataset/get_or_create/
POSTImport dataset(s) with associated databases/api/v1/dataset/import/
GETGet related fields data (dataset-related-column-name)/api/v1/dataset/related/{column_name}
PUTWarm up the cache for each chart powered by the given table/api/v1/dataset/warm_up_cache
</details> <details> <summary><strong>Database</strong> (31 endpoints) — Manage database connections and metadata.</summary>
MethodEndpointDescription
GETGet a list of databases/api/v1/database/
POSTCreate a new database/api/v1/database/
GETGet metadata information about this API resource (database--info)/api/v1/database/_info
DELETEDelete a database/api/v1/database/{pk}
GETGet a database/api/v1/database/{pk}
PUTChange a database/api/v1/database/{pk}
GETGet all catalogs from a database/api/v1/database/{pk}/catalogs/
GETGet a database connection info/api/v1/database/{pk}/connection
GETGet function names supported by a database/api/v1/database/{pk}/function_names/
GETGet charts and dashboards count associated to a database/api/v1/database/{pk}/related_objects/
GETThe list of the database schemas where to upload information/api/v1/database/{pk}/schemas_access_for_file_upload/
GETGet all schemas from a database/api/v1/database/{pk}/schemas/
GETGet database select star for table (database-pk-select-star-table-name)/api/v1/database/{pk}/select_star/{table_name}/
GETGet database select star for table (database-pk-select-star-table-name-schema-name)/api/v1/database/{pk}/select_star/{table_name}/{schema_name}/
DELETEDelete a SSH tunnel/api/v1/database/{pk}/ssh_tunnel/
POSTRe-sync all permissions for a database connection/api/v1/database/{pk}/sync_permissions/
GETGet table extra metadata (database-pk-table-extra-table-name-schema-name)/api/v1/database/{pk}/table_extra/{table_name}/{schema_name}/
GETGet table metadata/api/v1/database/{pk}/table_metadata/
GETGet table extra metadata (database-pk-table-metadata-extra)/api/v1/database/{pk}/table_metadata/extra/
GETGet database table metadata/api/v1/database/{pk}/table/{table_name}/{schema_name}/
GETGet a list of tables for given database/api/v1/database/{pk}/tables/
POSTUpload a file to a database table/api/v1/database/{pk}/upload/
POSTValidate arbitrary SQL/api/v1/database/{pk}/validate_sql/
GETGet names of databases currently available/api/v1/database/available/
GETDownload database(s) and associated dataset(s) as a zip file/api/v1/database/export/
POSTImport database(s) with associated datasets/api/v1/database/import/
GETReceive personal access tokens from OAuth2/api/v1/database/oauth2/
GETGet related fields data (database-related-column-name)/api/v1/database/related/{column_name}
POSTTest a database connection/api/v1/database/test_connection/
POSTUpload a file and returns file metadata/api/v1/database/upload_metadata/
POSTValidate database connection parameters/api/v1/database/validate_parameters/
</details>

Data Exploration

<details> <summary><strong>Explore</strong> (1 endpoints) — Chart exploration and data querying endpoints.</summary>
MethodEndpointDescription
GETAssemble Explore related information in a single endpoint/api/v1/explore/
</details> <details> <summary><strong>SQL Lab</strong> (6 endpoints) — Execute SQL queries and manage SQL Lab sessions.</summary>
MethodEndpointDescription
GETGet the bootstrap data for SqlLab page/api/v1/sqllab/
POSTEstimate the SQL query execution cost/api/v1/sqllab/estimate/
POSTExecute a SQL query/api/v1/sqllab/execute/
GETExport the SQL query results to a CSV/api/v1/sqllab/export/{client_id}/
POSTFormat SQL code/api/v1/sqllab/format_sql/
GETGet the result of a SQL query execution/api/v1/sqllab/results/
</details> <details> <summary><strong>Queries</strong> (17 endpoints) — View and manage SQL Lab query history.</summary>
MethodEndpointDescription
GETGet a list of queries/api/v1/query/
GETGet query detail information/api/v1/query/{pk}
GETGet distinct values from field data (query-distinct-column-name)/api/v1/query/distinct/{column_name}
GETGet related fields data (query-related-column-name)/api/v1/query/related/{column_name}
POSTManually stop a query with client_id/api/v1/query/stop
GETGet a list of queries that changed after last_updated_ms/api/v1/query/updated_since
DELETEBulk delete saved queries/api/v1/saved_query/
GETGet a list of saved queries/api/v1/saved_query/
POSTCreate a saved query/api/v1/saved_query/
GETGet metadata information about this API resource (saved-query--info)/api/v1/saved_query/_info
DELETEDelete a saved query/api/v1/saved_query/{pk}
GETGet a saved query/api/v1/saved_query/{pk}
PUTUpdate a saved query/api/v1/saved_query/{pk}
GETGet distinct values from field data (saved-query-distinct-column-name)/api/v1/saved_query/distinct/{column_name}
GETDownload multiple saved queries as YAML files/api/v1/saved_query/export/
POSTImport saved queries with associated databases/api/v1/saved_query/import/
GETGet related fields data (saved-query-related-column-name)/api/v1/saved_query/related/{column_name}
</details> <details> <summary><strong>Datasources</strong> (1 endpoints) — Query datasource metadata and column values.</summary>
MethodEndpointDescription
GETGet possible values for a datasource column/api/v1/datasource/{datasource_type}/{datasource_id}/column/{column_name}/values/
</details> <details> <summary><strong>Advanced Data Type</strong> (2 endpoints) — Endpoints for advanced data type operations and conversions.</summary>
MethodEndpointDescription
GETReturn an AdvancedDataTypeResponse/api/v1/advanced_data_type/convert
GETReturn a list of available advanced data types/api/v1/advanced_data_type/types
</details>

Organization & Customization

<details> <summary><strong>Tags</strong> (15 endpoints) — Organize assets with tags.</summary>
MethodEndpointDescription
DELETEBulk delete tags/api/v1/tag/
GETGet a list of tags/api/v1/tag/
POSTCreate a tag/api/v1/tag/
GETGet metadata information about tag API endpoints/api/v1/tag/_info
POSTAdd tags to an object/api/v1/tag/{object_type}/{object_id}/
DELETEDelete a tagged object/api/v1/tag/{object_type}/{object_id}/{tag}/
DELETEDelete a tag/api/v1/tag/{pk}
GETGet a tag detail information/api/v1/tag/{pk}
PUTUpdate a tag/api/v1/tag/{pk}
DELETEDelete tag by pk favorites/api/v1/tag/{pk}/favorites/
POSTCreate tag by pk favorites/api/v1/tag/{pk}/favorites/
POSTBulk create tags and tagged objects/api/v1/tag/bulk_create
GETGet tag favorite status/api/v1/tag/favorite_status/
GETGet all objects associated with a tag/api/v1/tag/get_objects/
GETGet related fields data (tag-related-column-name)/api/v1/tag/related/{column_name}
</details> <details> <summary><strong>Annotation Layers</strong> (14 endpoints) — Manage annotation layers and annotations for charts.</summary>
MethodEndpointDescription
DELETEDelete multiple annotation layers in a bulk operation/api/v1/annotation_layer/
GETGet a list of annotation layers (annotation-layer)/api/v1/annotation_layer/
POSTCreate an annotation layer (annotation-layer)/api/v1/annotation_layer/
GETGet metadata information about this API resource (annotation-layer--info)/api/v1/annotation_layer/_info
DELETEDelete annotation layer (annotation-layer-pk)/api/v1/annotation_layer/{pk}
GETGet an annotation layer (annotation-layer-pk)/api/v1/annotation_layer/{pk}
PUTUpdate an annotation layer (annotation-layer-pk)/api/v1/annotation_layer/{pk}
DELETEBulk delete annotation layers/api/v1/annotation_layer/{pk}/annotation/
GETGet a list of annotation layers (annotation-layer-pk-annotation)/api/v1/annotation_layer/{pk}/annotation/
POSTCreate an annotation layer (annotation-layer-pk-annotation)/api/v1/annotation_layer/{pk}/annotation/
DELETEDelete annotation layer (annotation-layer-pk-annotation-annotation-id)/api/v1/annotation_layer/{pk}/annotation/{annotation_id}
GETGet an annotation layer (annotation-layer-pk-annotation-annotation-id)/api/v1/annotation_layer/{pk}/annotation/{annotation_id}
PUTUpdate an annotation layer (annotation-layer-pk-annotation-annotation-id)/api/v1/annotation_layer/{pk}/annotation/{annotation_id}
GETGet related fields data (annotation-layer-related-column-name)/api/v1/annotation_layer/related/{column_name}
</details> <details> <summary><strong>CSS Templates</strong> (8 endpoints) — Manage CSS templates for custom dashboard styling.</summary>
MethodEndpointDescription
DELETEBulk delete CSS templates/api/v1/css_template/
GETGet a list of CSS templates/api/v1/css_template/
POSTCreate a CSS template/api/v1/css_template/
GETGet metadata information about this API resource (css-template--info)/api/v1/css_template/_info
DELETEDelete a CSS template/api/v1/css_template/{pk}
GETGet a CSS template/api/v1/css_template/{pk}
PUTUpdate a CSS template/api/v1/css_template/{pk}
GETGet related fields data (css-template-related-column-name)/api/v1/css_template/related/{column_name}
</details>

Sharing & Embedding

<details> <summary><strong>Dashboard Permanent Link</strong> (2 endpoints) — Create and retrieve permanent links to dashboard states.</summary>
MethodEndpointDescription
POSTCreate a new dashboard's permanent link/api/v1/dashboard/{pk}/permalink
GETGet dashboard's permanent link state/api/v1/dashboard/permalink/{key}
</details> <details> <summary><strong>Explore Permanent Link</strong> (2 endpoints) — Create and retrieve permanent links to chart explore states.</summary>
MethodEndpointDescription
POSTCreate a new permanent link (explore-permalink)/api/v1/explore/permalink
GETGet chart's permanent link state/api/v1/explore/permalink/{key}
</details> <details> <summary><strong>SQL Lab Permanent Link</strong> (2 endpoints) — Create and retrieve permanent links to SQL Lab states.</summary>
MethodEndpointDescription
POSTCreate a new permanent link (sqllab-permalink)/api/v1/sqllab/permalink
GETGet permanent link state for SQLLab editor./api/v1/sqllab/permalink/{key}
</details> <details> <summary><strong>Embedded Dashboard</strong> (1 endpoints) — Configure embedded dashboard settings.</summary>
MethodEndpointDescription
GETGet a report schedule log (embedded-dashboard-uuid)/api/v1/embedded_dashboard/{uuid}
</details> <details> <summary><strong>Dashboard Filter State</strong> (4 endpoints) — Manage temporary filter state for dashboards.</summary>
MethodEndpointDescription
POSTCreate a dashboard's filter state/api/v1/dashboard/{pk}/filter_state
DELETEDelete a dashboard's filter state value/api/v1/dashboard/{pk}/filter_state/{key}
GETGet a dashboard's filter state value/api/v1/dashboard/{pk}/filter_state/{key}
PUTUpdate a dashboard's filter state value/api/v1/dashboard/{pk}/filter_state/{key}
</details> <details> <summary><strong>Explore Form Data</strong> (4 endpoints) — Manage temporary form data for chart exploration.</summary>
MethodEndpointDescription
POSTCreate a new form_data/api/v1/explore/form_data
DELETEDelete a form_data/api/v1/explore/form_data/{key}
GETGet a form_data/api/v1/explore/form_data/{key}
PUTUpdate an existing form_data/api/v1/explore/form_data/{key}
</details>

Scheduling & Alerts

<details> <summary><strong>Report Schedules</strong> (11 endpoints) — Configure scheduled reports and alerts.</summary>
MethodEndpointDescription
DELETEBulk delete report schedules/api/v1/report/
GETGet a list of report schedules/api/v1/report/
POSTCreate a report schedule/api/v1/report/
GETGet metadata information about this API resource (report--info)/api/v1/report/_info
DELETEDelete a report schedule/api/v1/report/{pk}
GETGet a report schedule/api/v1/report/{pk}
PUTUpdate a report schedule/api/v1/report/{pk}
GETGet a list of report schedule logs/api/v1/report/{pk}/log/
GETGet a report schedule log (report-pk-log-log-id)/api/v1/report/{pk}/log/{log_id}
GETGet related fields data (report-related-column-name)/api/v1/report/related/{column_name}
GETGet slack channels/api/v1/report/slack_channels/
</details>

Security & Access Control

<details> <summary><strong>Security Roles</strong> (10 endpoints) — Manage security roles and their permissions.</summary>
MethodEndpointDescription
GETGet security roles/api/v1/security/roles/
POSTCreate security roles/api/v1/security/roles/
GETGet security roles info/api/v1/security/roles/_info
DELETEDelete security roles by pk/api/v1/security/roles/{pk}
GETGet security roles by pk/api/v1/security/roles/{pk}
PUTUpdate security roles by pk/api/v1/security/roles/{pk}
POSTCreate security roles by role_id permissions/api/v1/security/roles/{role_id}/permissions
GETGet security roles by role_id permissions/api/v1/security/roles/{role_id}/permissions/
PUTUpdate security roles by role_id users/api/v1/security/roles/{role_id}/users
GETList roles/api/v1/security/roles/search/
</details> <details> <summary><strong>Security Users</strong> (6 endpoints) — Manage user accounts.</summary>
MethodEndpointDescription
GETGet security users/api/v1/security/users/
POSTCreate security users/api/v1/security/users/
GETGet security users info/api/v1/security/users/_info
DELETEDelete security users by pk/api/v1/security/users/{pk}
GETGet security users by pk/api/v1/security/users/{pk}
PUTUpdate security users by pk/api/v1/security/users/{pk}
</details> <details> <summary><strong>Security Permissions</strong> (3 endpoints) — View available permissions.</summary>
MethodEndpointDescription
GETGet security permissions/api/v1/security/permissions/
GETGet security permissions info/api/v1/security/permissions/_info
GETGet security permissions by pk/api/v1/security/permissions/{pk}
</details> <details> <summary><strong>Security Resources (View Menus)</strong> (6 endpoints) — Manage security resources (view menus).</summary>
MethodEndpointDescription
GETGet security resources/api/v1/security/resources/
POSTCreate security resources/api/v1/security/resources/
GETGet security resources info/api/v1/security/resources/_info
DELETEDelete security resources by pk/api/v1/security/resources/{pk}
GETGet security resources by pk/api/v1/security/resources/{pk}
PUTUpdate security resources by pk/api/v1/security/resources/{pk}
</details> <details> <summary><strong>Security Permissions on Resources (View Menus)</strong> (6 endpoints) — Manage permission-resource mappings.</summary>
MethodEndpointDescription
GETGet security permissions resources/api/v1/security/permissions-resources/
POSTCreate security permissions resources/api/v1/security/permissions-resources/
GETGet security permissions resources info/api/v1/security/permissions-resources/_info
DELETEDelete security permissions resources by pk/api/v1/security/permissions-resources/{pk}
GETGet security permissions resources by pk/api/v1/security/permissions-resources/{pk}
PUTUpdate security permissions resources by pk/api/v1/security/permissions-resources/{pk}
</details> <details> <summary><strong>Row Level Security</strong> (8 endpoints) — Manage row-level security rules for data access control.</summary>
MethodEndpointDescription
DELETEBulk delete RLS rules/api/v1/rowlevelsecurity/
GETGet a list of RLS/api/v1/rowlevelsecurity/
POSTCreate a new RLS rule/api/v1/rowlevelsecurity/
GETGet metadata information about this API resource (rowlevelsecurity--info)/api/v1/rowlevelsecurity/_info
DELETEDelete an RLS/api/v1/rowlevelsecurity/{pk}
GETGet an RLS/api/v1/rowlevelsecurity/{pk}
PUTUpdate an RLS rule/api/v1/rowlevelsecurity/{pk}
GETGet related fields data (rowlevelsecurity-related-column-name)/api/v1/rowlevelsecurity/related/{column_name}
</details>

Import/Export & Administration

<details> <summary><strong>Import/export</strong> (2 endpoints) — Import and export Superset assets (dashboards, charts, databases).</summary>
MethodEndpointDescription
GETExport all assets/api/v1/assets/export/
POSTImport multiple assets/api/v1/assets/import/
</details> <details> <summary><strong>CacheRestApi</strong> (1 endpoints) — Cache management and invalidation operations.</summary>
MethodEndpointDescription
POSTInvalidate cache records and remove the database records/api/v1/cachekey/invalidate
</details> <details> <summary><strong>LogRestApi</strong> (4 endpoints) — Access audit logs and activity history.</summary>
MethodEndpointDescription
GETGet a list of logs/api/v1/log/
POSTCreate log/api/v1/log/
GETGet a log detail information/api/v1/log/{pk}
GETGet recent activity data for a user/api/v1/log/recent_activity/
</details>

User & System

<details> <summary><strong>Current User</strong> (2 endpoints) — Get information about the currently authenticated user.</summary>
MethodEndpointDescription
GETGet the user object/api/v1/me/
GETGet the user roles/api/v1/me/roles/
</details> <details> <summary><strong>User</strong> (1 endpoints) — User profile and preferences.</summary>
MethodEndpointDescription
GETGet the user avatar/api/v1/user/{user_id}/avatar.png
</details> <details> <summary><strong>Menu</strong> (1 endpoints) — Get the Superset menu structure.</summary>
MethodEndpointDescription
GETGet menu/api/v1/menu/
</details> <details> <summary><strong>Available Domains</strong> (1 endpoints) — Get available domains for the Superset instance.</summary>
MethodEndpointDescription
GETGet all available domains/api/v1/available_domains/
</details> <details> <summary><strong>AsyncEventsRestApi</strong> (1 endpoints) — Real-time event streaming via Server-Sent Events (SSE).</summary>
MethodEndpointDescription
GETRead off of the Redis events stream/api/v1/async_event/
</details> <details> <summary><strong>OpenApi</strong> (1 endpoints) — Access the OpenAPI specification.</summary>
MethodEndpointDescription
GETGet api by version openapi/api/{version}/_openapi
</details>

Additional Resources