0
# REST API
1

2
Comprehensive RESTful API for programmatic access to all Superset functionality including dashboards, charts, datasets, users, and administrative operations.
3

4
## Capabilities
5

6
### Chart API
7

8
CRUD operations and data export for charts and visualizations.
9

10
```python { .api }
11
class ChartRestApi(BaseSupersetModelRestApi):
12
    """REST API for chart management."""
13
    
14
    def get(self, pk: int) -> Response:
15
        """
16
        Get chart by ID.
17
        
18
        Args:
19
            pk: Chart primary key
20
            
21
        Returns:
22
            JSON response with chart metadata and configuration
23
        """
24
    
25
    def post(self) -> Response:
26
        """
27
        Create new chart.
28
        
29
        Request Body:
30
            slice_name: str - Chart name
31
            viz_type: str - Visualization type
32
            datasource_id: int - Source dataset ID
33
            datasource_type: str - Source dataset type
34
            params: str - JSON encoded chart parameters
35
            
36
        Returns:
37
            JSON response with created chart details
38
        """
39
    
40
    def put(self, pk: int) -> Response:
41
        """
42
        Update existing chart.
43
        
44
        Args:
45
            pk: Chart primary key
46
            
47
        Request Body:
48
            slice_name: str - Updated chart name
49
            params: str - Updated chart parameters
50
            
51
        Returns:
52
            JSON response with updated chart details
53
        """
54
    
55
    def delete(self, pk: int) -> Response:
56
        """
57
        Delete chart.
58
        
59
        Args:
60
            pk: Chart primary key
61
            
62
        Returns:
63
            JSON response confirming deletion
64
        """
65
    
66
    def data(self, pk: int) -> Response:
67
        """
68
        Get chart data for visualization rendering.
69
        
70
        Args:
71
            pk: Chart primary key
72
            
73
        Query Parameters:
74
            format: str - Response format (json, csv)
75
            force: bool - Force refresh cached data
76
            
77
        Returns:
78
            JSON response with chart data and metadata
79
        """
80
    
81
    def export(self) -> Response:
82
        """
83
        Export chart configurations.
84
        
85
        Query Parameters:
86
            q: str - Query filter for charts to export
87
            
88
        Returns:
89
            JSON response with exportable chart configurations
90
        """
91
```
92

93
**Usage Examples:**
94

95
```python
96
import requests
97

98
# Get chart details
99
response = requests.get('http://superset-host/api/v1/chart/123')
100
chart = response.json()
101

102
# Create new chart
103
chart_data = {
104
    'slice_name': 'My Chart',
105
    'viz_type': 'table',
106
    'datasource_id': 1,
107
    'datasource_type': 'table',
108
    'params': '{"metrics": ["count"]}'
109
}
110
response = requests.post('http://superset-host/api/v1/chart/', json=chart_data)
111

112
# Get chart data
113
response = requests.get('http://superset-host/api/v1/chart/123/data')
114
data = response.json()
115
```
116

117
### Dashboard API
118

119
Dashboard management, layout operations, and access control.
120

121
```python { .api }
122
class DashboardRestApi(BaseSupersetModelRestApi):
123
    """REST API for dashboard management."""
124
    
125
    def get(self, pk: int) -> Response:
126
        """
127
        Get dashboard by ID.
128
        
129
        Args:
130
            pk: Dashboard primary key
131
            
132
        Returns:
133
            JSON response with dashboard metadata, layout, and charts
134
        """
135
    
136
    def post(self) -> Response:
137
        """
138
        Create new dashboard.
139
        
140
        Request Body:
141
            dashboard_title: str - Dashboard title
142
            position_json: str - JSON encoded layout
143
            css: str - Custom CSS styling
144
            
145
        Returns:
146
            JSON response with created dashboard details
147
        """
148
    
149
    def put(self, pk: int) -> Response:
150
        """
151
        Update dashboard.
152
        
153
        Args:
154
            pk: Dashboard primary key
155
            
156
        Request Body:
157
            dashboard_title: str - Updated title
158
            position_json: str - Updated layout
159
            
160
        Returns:
161
            JSON response with updated dashboard details
162
        """
163
    
164
    def export(self) -> Response:
165
        """
166
        Export dashboard configurations.
167
        
168
        Query Parameters:
169
            q: str - Query filter for dashboards to export
170
            
171
        Returns:
172
            JSON response with exportable dashboard configurations
173
        """
174
    
175
    def import_(self) -> Response:
176
        """
177
        Import dashboard configurations.
178
        
179
        Request Body:
180
            formData: file - Dashboard export file
181
            overwrite: bool - Overwrite existing dashboards
182
            
183
        Returns:
184
            JSON response with import results
185
        """
186
```
187

188
**Usage Examples:**
189

190
```python
191
# Get dashboard
192
response = requests.get('http://superset-host/api/v1/dashboard/456')
193
dashboard = response.json()
194

195
# Update dashboard layout
196
layout_data = {
197
    'position_json': '{"CHART-123": {"x": 0, "y": 0, "w": 6, "h": 4}}'
198
}
199
response = requests.put('http://superset-host/api/v1/dashboard/456', json=layout_data)
200
```
201

202
### Dataset API
203

204
Dataset configuration, column metadata, and data source management.
205

206
```python { .api }
207
class DatasetRestApi(BaseSupersetModelRestApi):
208
    """REST API for dataset management."""
209
    
210
    def get(self, pk: int) -> Response:
211
        """
212
        Get dataset by ID.
213
        
214
        Args:
215
            pk: Dataset primary key
216
            
217
        Returns:
218
            JSON response with dataset metadata and column information
219
        """
220
    
221
    def post(self) -> Response:
222
        """
223
        Create new dataset.
224
        
225
        Request Body:
226
            table_name: str - Table name
227
            database: int - Database ID
228
            schema: str - Schema name (optional)
229
            
230
        Returns:
231
            JSON response with created dataset details
232
        """
233
    
234
    def refresh(self, pk: int) -> Response:
235
        """
236
        Refresh dataset metadata.
237
        
238
        Args:
239
            pk: Dataset primary key
240
            
241
        Returns:
242
            JSON response confirming metadata refresh
243
        """
244
    
245
    def samples(self, pk: int) -> Response:
246
        """
247
        Get sample data from dataset.
248
        
249
        Args:
250
            pk: Dataset primary key
251
            
252
        Query Parameters:
253
            force: bool - Force refresh of sample data
254
            
255
        Returns:
256
            JSON response with sample rows and column information
257
        """
258
```
259

260
### Database API
261

262
Database connection management and metadata operations.
263

264
```python { .api }
265
class DatabaseRestApi(BaseSupersetModelRestApi):
266
    """REST API for database connection management."""
267
    
268
    def get(self, pk: int) -> Response:
269
        """
270
        Get database connection by ID.
271
        
272
        Args:
273
            pk: Database primary key
274
            
275
        Returns:
276
            JSON response with database connection details
277
        """
278
    
279
    def post(self) -> Response:
280
        """
281
        Create new database connection.
282
        
283
        Request Body:
284
            database_name: str - Connection name
285
            sqlalchemy_uri: str - Database connection URI
286
            expose_in_sqllab: bool - Allow SQL Lab access
287
            
288
        Returns:
289
            JSON response with created database details
290
        """
291
    
292
    def test_connection(self) -> Response:
293
        """
294
        Test database connection.
295
        
296
        Request Body:
297
            sqlalchemy_uri: str - Database URI to test
298
            
299
        Returns:
300
            JSON response with connection test results
301
        """
302
    
303
    def schemas(self, pk: int) -> Response:
304
        """
305
        Get available schemas for database.
306
        
307
        Args:
308
            pk: Database primary key
309
            
310
        Returns:
311
            JSON response with list of available schemas
312
        """
313
    
314
    def tables(self, pk: int) -> Response:
315
        """
316
        Get available tables for database schema.
317
        
318
        Args:
319
            pk: Database primary key
320
            
321
        Query Parameters:
322
            schema_name: str - Schema to list tables from
323
            
324
        Returns:
325
            JSON response with list of tables and metadata
326
        """
327
```
328

329
### Query API
330

331
SQL Lab query execution and management.
332

333
```python { .api }
334
class QueryRestApi(BaseSupersetModelRestApi):
335
    """REST API for query execution and management."""
336
    
337
    def get(self, pk: int) -> Response:
338
        """
339
        Get query by ID.
340
        
341
        Args:
342
            pk: Query primary key
343
            
344
        Returns:
345
            JSON response with query metadata and results
346
        """
347
    
348
    def post(self) -> Response:
349
        """
350
        Execute new SQL query.
351
        
352
        Request Body:
353
            sql: str - SQL query to execute
354
            database_id: int - Database to run query against
355
            schema: str - Schema context (optional)
356
            
357
        Returns:
358
            JSON response with query results or execution status
359
        """
360
    
361
    def results(self, pk: int) -> Response:
362
        """
363
        Get query execution results.
364
        
365
        Args:
366
            pk: Query primary key
367
            
368
        Query Parameters:
369
            key: str - Results backend key
370
            
371
        Returns:
372
            JSON response with query results and metadata
373
        """
374
    
375
    def stop(self, pk: int) -> Response:
376
        """
377
        Stop running query.
378
        
379
        Args:
380
            pk: Query primary key
381
            
382
        Returns:
383
            JSON response confirming query cancellation
384
        """
385
```
386

387
### Security API
388

389
User management, roles, and permissions.
390

391
```python { .api }
392
class SecurityRestApi(BaseApi):
393
    """REST API for security and user management."""
394
    
395
    def login(self) -> Response:
396
        """
397
        User authentication.
398
        
399
        Request Body:
400
            username: str - User login name
401
            password: str - User password
402
            provider: str - Authentication provider (optional)
403
            
404
        Returns:
405
            JSON response with authentication token and user details
406
        """
407
    
408
    def refresh(self) -> Response:
409
        """
410
        Refresh authentication token.
411
        
412
        Headers:
413
            Authorization: Bearer <refresh_token>
414
            
415
        Returns:
416
            JSON response with new access token
417
        """
418
    
419
    def guest_token(self) -> Response:
420
        """
421
        Generate guest access token.
422
        
423
        Request Body:
424
            resources: List[Dict] - Resources to grant access to
425
            rls: List[Dict] - Row-level security rules
426
            user: Dict - Guest user attributes
427
            
428
        Returns:
429
            JSON response with guest token
430
        """
431
    
432
    def csrf_token(self) -> Response:
433
        """
434
        Get CSRF protection token.
435
        
436
        Returns:
437
            JSON response with CSRF token
438
        """
439
```
440

441
## API Response Formats
442

443
### Standard Response Structure
444

445
```python { .api }
446
# Success response
447
{
448
    "id": int,
449
    "result": Dict[str, Any],
450
    "count": int
451
}
452

453
# Error response  
454
{
455
    "message": str,
456
    "errors": List[Dict[str, Any]],
457
    "status": int
458
}
459

460
# List response
461
{
462
    "count": int,
463
    "ids": List[int],
464
    "result": List[Dict[str, Any]]
465
}
466
```
467

468
### Query Parameters
469

470
```python { .api }
471
# Filtering
472
q: str  # JSON encoded query filters
473

474
# Pagination  
475
page: int  # Page number (0-based)
476
page_size: int  # Results per page
477

478
# Sorting
479
order_column: str  # Column to sort by
480
order_direction: str  # 'asc' or 'desc'
481

482
# Field selection
483
columns: List[str]  # Specific columns to include
484
```
485

486
## Authentication
487

488
All API endpoints require authentication via JWT tokens:
489

490
```python
491
headers = {
492
    'Authorization': 'Bearer <access_token>',
493
    'Content-Type': 'application/json'
494
}
495

496
response = requests.get('http://superset-host/api/v1/chart/', headers=headers)
497
```