The Preset API

Overview

The Preset REST API is a powerful feature that provides access to core functional aspects of both Preset Manager and Superset.

The API supports the following areas of Preset:

• User and Team Management
• Workspace Management
• Connection Management
• Visualization Management

This article focuses on the most relevant endpoints across all of the above functional areas of Preset.

Authentication

All Preset Manager and Superset REST APIs require authentication — the mechanism for both are the same. This means that the following steps can also be used for leveraging the Superset REST API.

In order to authenticate, an API key must be generated. Every API key consists of the following:

• Title: A human readable title.
• Description: A description of the key's purpose (optional).
• Name: An automatically-generated key name.
• Secret: An automatically-generated secret.
• Last used: A timestamp with the last date time this key was exchanged by a JWT token.

An API Key will authenticate on behalf of the user for both Preset Manager and Superset.

Generate an API Key

To generate an API key, from Preset Manager, hover your cursor over the initials icon and, in the sub-menu, select Manage User Settings.

In the API Keys section, select + Generate New API Key.

The Generate a New API Key panel appears.

In the Key Title field, enter a name for the new API key.

In the Key Description field, enter a brief descripton of the API key.

Select Submit.

The Token field will automatically populate with a generated token.

Likewise, the Secret field will automatically populate with a secret.

When ready, select OK.

The newly-created API key appears in the API Keys section.

By default, the API key will be activated — to deactivate, toggle the Active slider to the off position.

To delete an API key, select the trash bin icon.

Using the Authentication Endpoint

First, use curl to retrieve the JWT token:

curl -X POST 'https://manage.app.preset.io/api/v1/auth' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{"name": "<API_KEY>", "secret": "<API_SECRET>"}'

...the JWT token can be used for bearer authentication:

{
  "payload": {
    "access_token": "<JWT_ACCESS_TOKEN>"
  }
}

Users can then use the access token to create an environment variable to facilitate its usage on subsequent calls:

export JWT_TOKEN=$(curl -X POST 'https://manage.app.preset.io/api/v1/auth' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{"name": "<API_KEY>", "secret": "<API_SECRET>"}' \
| jq -r '.payload.access_token')

API Parameters

• Preset APIs use the Team_Slug to identify your team. This is available to Admins when accessing the Team Administration:
  

  The Team_Slug can be found on the URL:

  https://manage.app.preset.io/app/teams/<Team_Slug>
  

  Alternatively, the Team_Slug can also be retrieved through the API, using the Retrieve Teams Based on User Membership API.

• User_IDs can be retrieved using the Retrieve Team Members API.

• The Team Role is specified on the API with the team_role_id parameter:

  • Use "team_role_id": 2 for User.
  • Use "team_role_id": 1 for Admin.

• The Invite_Code can be retrieved using the Retrieve Pending Team Invites API.

• The Workspace_ID can be retrieved using the Retrieve Workspaces that Belong to a Team API.

• The Workspace_Slug and Region can be found directly on the Workspace URL:

  https://<Workspace_Slug>.<Region>.app.preset.io/superset/welcome/
  

  Alternatively, the Workspace_Slug can be retrieved through the Retrieve Workspaces that Belong to a Team API (as the name parameter). The Region can also be retrieved through this API, according to below table:

  Location	Region
  US East Coast (us-east-1)	us2a
  US West Coast (us-west-2)	us1a
  Europe (eu-north-1)	eu5a
  Asia-Pacific (ap-northeast-1)	ap1a

*: The API key must be from a Team Administrator.

User and Team Management

Retrieve Teams Based on User Membership

curl -X GET 'https://manage.app.preset.io/api/v1/teams' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN"

Create a Team Invite *

curl -X POST 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/invites' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN" \
--data-raw '{"team_role_id": 2, "email": "new_user@awesome.org"}'

Create Multiple Team Invites *

curl -X POST 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/invites/many' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN" \
--data-raw '{"invites": [{"team_role_id": 2, "email": "new_user@awesome.org"}]}'

Retrieve Pending Team Invites *

curl -X GET 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/invites' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN"

Delete Invite Code *

curl -X DELETE 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/invites/<Invite_Code>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN"

Resend Invite

curl -X POST 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/invites/<Invite_Code>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN"

Retrieve Team Members *

curl -X GET 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/memberships' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN"

Change User Role *

curl -X PATCH 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/memberships/<User_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN" \
  --data-raw '{"team_role_id": 2}'

Delete a Team Member *

curl -X DELETE 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/memberships/<User_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN"

Change Team Title *

curl -X PUT 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN" \
  --data-raw '{"title": "<New Title>"}'

Workspace Management

Create Workspace for a Team *

curl -X POST 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/workspaces' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN" \
  --data-raw '{"title": "<Workspace Title>"}'

Retrieve Workspaces that Belong to a Team

curl -X GET 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/workspaces' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN"

Retrieve Workspace Users and Roles

curl -X GET 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/workspaces/<Workspace_ID>/memberships' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN"

Change Workspace Role *

curl -X PUT 'https://manage.app.preset.io/api/v1/teams/<Team_Slug>/workspaces/<Workspace_ID>/membership' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $JWT_TOKEN" \
  --data-raw '{"role_identifier": "PresetAlpha", "user_id": 2}'

Role identifiers based on workspace role

Connection Management

Create a Database

curl -X POST 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/database 
\ -H 'Content-Type: application/json'
\ -H 'Accept: application/json' 
\ -H "Authorization: Bearer $JWT_TOKEN" 
\ --data-raw '{
  "allow_csv_upload": true,
  "allow_ctas": true,
  "allow_cvas": true,
  "allow_dml": true,
  "allow_multi_schema_metadata_fetch": true,
  "allow_run_async": true,
  "cache_timeout": 0,
  "database_name": "string",
  "encrypted_extra": "string",
  "expose_in_sqllab": true,
  "extra": "string",
  "force_ctas_schema": "string",
  "impersonate_user": true,
  "server_cert": "string",
  "sqlalchemy_uri": "string"
}'

Example of a database connection call:

curl -X POST 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/database 
\ -H 'Content-Type: application/json'
\ -H 'Accept: application/json' 
 \ -H "Authorization: Bearer $JWT_TOKEN" 
\ --data-raw '{"allow_csv_upload": true,
 "allow_ctas": true,
 "allow_cvas": true,
 "allow_dml": true,
 "allow_multi_schema_metadata_fetch": true,
 	"allow_run_async": true,
 	"cache_timeout": 0,
 	"database_name": "test",
 	"expose_in_sqllab": true,
 	"impersonate_user": false,
 	"sqlalchemy_uri": "postgresql://…”
}’

Notes:

• If you encounter a 400 Bad Request: The referrer header is missing error, then add another header with the key referer: https://<Workspace_Slug>.<Region>.app.preset.io/.
• If you are getting a connection failure, then change the impersonate_user field to false.

Add a Dataset

curl -X POST 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/dataset \ -H 
'Content-Type: application/json' \ -H 'Accept: application/json' \ -H "Authorization: Bearer $JWT_TOKEN" \ 
--data-raw '{  "database": 0,
  "owners": [
    0
  ],
  "schema": "string",
  "table_name": "string"
}’

Example of a dataset connection call:

curl -X POST 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/dataset \ -H 
'Content-Type: application/json' \ -H 'Accept: application/json' \ -H "Authorization: Bearer $JWT_TOKEN" \ 
--data-raw ' {
 "database": 11,
 "schema": "public",
 "table_name": "test_cities"
}’

Notes:

• If you encounter a 400 Bad Request: The referrer header is missing error, then add another header with the key referer: https://<Workspace_Slug>.<Region>.app.preset.io/.
• If owners are not specified in call, the owner will default to the user who is making the API request.

Visualization Management

Create a Chart

curl -X POST 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/chart \ -H 
'Content-Type: application/json' \ -H 'Accept: application/json' \ -H "Authorization: Bearer $JWT_TOKEN" \ 
--data-raw '{
 	 "cache_timeout": 0,
  	"dashboards": [0],
 	"datasource_id": 0,
  	"datasource_name": "string",
  	"datasource_type": "druid",
  	"description": "string",
  	"owners": [0],
  	"params": "string",
  	"slice_name": "string",
  	"viz_type": [
    	"bar",
    	"line_multi",
    	"area",
    	"Table", etc.
  	]
}

Example of a create chart call:

curl -X POST 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/chart \ -H 
'Content-Type: application/json' \ -H 'Accept: application/json' \ -H "Authorization: Bearer $JWT_TOKEN" \ 
--data-raw '{
 "cache_timeout": 0,
 "dashboards": [
   12
 ],
 "datasource_id": 28,
 	 "params": "JSON FOR CHART",
 "datasource_name": "test_cities",
 "datasource_type": "table",
 "slice_name": "Test",
 "viz_type": "table"
}’

Notes:

• If you encounter a 400 Bad Request: The referrer header is missing error, then add another header with the key referer: https://<Workspace_Slug>.<Region>.app.preset.io/.
• If owners are not specified in call, the owner will default to the user who is making the API request.

Create a Dashboard

curl -X POST 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/dashboard' 
\ -H 'Content-Type: application/json'
\ -H 'Accept: application/json' 
 \ -H "Authorization: Bearer $JWT_TOKEN" 
\ --data-raw '{
  "css": "string",
 	 "dashboard_title": "string",
 	 "json_metadata": "string",
 	 "owners": [0],
 	 "position_json": "string",
  	"published": true,
 	 "slug": "string"
}'

Example of a blank, unpublished dashboard:

curl -X POST 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/dashboard'
 \ -H 'Content-Type: application/json' 
 \ -H 'Accept: application/json' 
\ -H "Authorization: Bearer $JWT_TOKEN"
 \ --data-raw '{
 	 "dashboard_title": "test",
  	   "published": false
}'

Notes:

• If you encounter a 400 Bad Request: The referrer header is missing error, then add another header with the key referer: https://<Workspace_Slug>.<Region>.app.preset.io/.
• If owners are not specified in call, the owner will default to the user who is making the API request.

Export a Dashboard

curl -X GET  'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/dashboard/export?q=!(<ids>)
 \ -H 'Content-Type: application/json'
 \ -H 'Accept: application/json' 
 \ -H "Authorization: Bearer $JWT_TOKEN"

Example:

curl -X GET  'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/dashboard/export?q=!(1,4)
\ -H 'Content-Type: application/json'
\ -H 'Accept: application/json' 
\ -H "Authorization: Bearer $JWT_TOKEN"

Import a Dashboard

curl 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/dashboard/import/' \
-X 'POST' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $JWT_TOKEN" \
-H 'Referer: https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/dashboard/' \
-F 'passwords={"databases/<Database_Yaml_File>": "<Database_Password>"}' \
-F 'formData=@<Dashboard_Zip_File>'

Import & Export Dashboards, Databases, and Datasets

The procedure discussed above is identical to importing & exporting dashboards, databases, and datasets. The only difference is that the /chart endpoint needs to be changed to the name of the component being imported or exported.

Notes:

• If you encounter a 400 Bad Request: The referrer header is missing error, then add another header with the key referer: https://<Workspace_Slug>.<Region>.app.preset.io/.
• The above uses an array of ids as rison query parameters. The id is the id of the chart you want to export; for example, q=!(1,2,3) or q=!(1).

Export an Image of a Chart

Generate the cached Image

curl -X GET  'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/chart/<Chart_ID>/cache_screenshot/'
 \ -H 'Content-Type: application/json'
 \ -H 'Accept: application/json'
\ -H "Authorization: Bearer $JWT_TOKEN"

This will give you the Digest of the cached image

Export it

wget -O <filename>.jpg -d --header='Content-Type: image' --header="Authorization: Bearer $JWT_TOKEN" https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/chart/<Chart_ID>/screenshot/<Digest>

Create an Alert

curl -X POST 'https://<Workspace_Slug>.<Region>.app.preset.io/api/v1/report/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'referer: https://<Workspace_Slug>.<Region>.app.preset.io/alert/list/?pageIndex=0&sortColumn=name&sortOrder=desc' \
  -H "Authorization: Bearer $JWT_TOKEN" \
  --data-raw '{"active":true,"creation_method":"alerts_reports","crontab":"0 * * * *","log_retention":90,"working_timeout":3600,"name":"APITEST","owners":[13],"recipients":[{"recipient_config_json":{"target":"testbody"},"type":"Email"}],"sql":"x","validator_config_json":{"op":">","threshold":"1"},"validator_type":"operator","force_screenshot":"false","timezone":"Europe/Andorra","description":"test","database":19,"dashboard":9,"chart":null,"type":"Alert","report_format":"PNG","context_markdown":"string"}' \
  --compressed