-
Print
-
DarkLight
-
PDF
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:
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.
Reminder: Safeguard the Secret
Please take a moment to select the Copy icon and then safely store it.
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.
- Use
-
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
andRegion
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 thename
parameter). TheRegion
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
Workspace Role | role_identifier |
---|---|
Workspace Admin | Admin |
Primary Contributor | PresetAlpha |
Limited Contributor | PresetGamma |
Viewer | PresetReportsOnly |
Dashboard Viewer | PresetDashboardsOnly |
No Access | PresetNoAccess |
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