Preset Manager endpoints for listing teams, listing and creating workspaces within a team, managing team membership, and minting guest tokens for embedded dashboards via POST /v1/teams/{team}/workspaces/{workspace}/guest-token/.
openapi: 3.0.1
info:
title: Preset API
description: >-
Specification of the Preset API. Preset is a managed cloud BI and analytics
platform powered by Apache Superset. The API has two surfaces: the Preset
Manager API at https://api.app.preset.io (authentication, teams, workspaces,
guest tokens) and a per-workspace proxy to the underlying Apache Superset
REST API reached at the workspace hostname pattern
{workspace-slug}.{region}.app.preset.io. Authenticate by exchanging an API
token name and secret at POST /v1/auth/ for a JWT, then pass it as a Bearer
token on subsequent requests.
termsOfService: https://preset.io/terms-and-conditions/
contact:
name: Preset Support
url: https://docs.preset.io
version: '1.0'
servers:
- url: https://api.app.preset.io
description: Preset Manager API (authentication, teams, workspaces, guest tokens)
- url: https://{workspaceSlug}.{region}.app.preset.io
description: Per-workspace proxy to the Apache Superset REST API
variables:
workspaceSlug:
default: my-workspace
description: The workspace slug returned by the workspaces endpoint
region:
default: us2a
description: The workspace region (e.g. us2a)
paths:
/v1/auth/:
post:
operationId: createToken
tags:
- Authentication
summary: Exchange API token credentials for a JWT access token
description: >-
Exchanges an API token name and secret (generated in Preset account
settings) for a short-lived JWT access token valid for a few hours.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthRequest'
responses:
'200':
description: A JWT access token payload.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResponse'
'401':
description: Invalid credentials.
/v1/teams/:
get:
operationId: getTeams
tags:
- Teams
summary: List teams
description: Returns the teams the authenticated principal belongs to.
security:
- bearerAuth: []
responses:
'200':
description: A list of teams.
content:
application/json:
schema:
$ref: '#/components/schemas/TeamList'
/v1/teams/{teamName}/workspaces/:
get:
operationId: getWorkspaces
tags:
- Workspaces
summary: List workspaces in a team
description: >-
Returns the workspaces belonging to a team, including each workspace
name (slug) and region used to construct the workspace proxy hostname.
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/TeamName'
responses:
'200':
description: A list of workspaces.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceList'
post:
operationId: createWorkspace
tags:
- Workspaces
summary: Create a workspace in a team
description: Creates a new Superset-backed workspace within a team.
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/TeamName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceCreate'
responses:
'201':
description: The created workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Workspace'
/v1/teams/{teamName}/workspaces/{workspaceName}/guest-token/:
post:
operationId: createGuestToken
tags:
- Workspaces
summary: Create a guest token for an embedded dashboard
description: >-
Mints a short-lived guest token (expires after about five minutes) that
authenticates an end user to view an embedded dashboard for the given
workspace.
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/TeamName'
- $ref: '#/components/parameters/WorkspaceName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GuestTokenRequest'
responses:
'200':
description: A guest token payload.
content:
application/json:
schema:
$ref: '#/components/schemas/GuestTokenResponse'
/api/v1/dashboard/:
get:
operationId: getDashboards
tags:
- Dashboards
summary: List dashboards (Superset proxy)
description: >-
Per-workspace proxy to the Apache Superset Dashboard API. Lists
dashboards in the workspace with optional Rison/JSON query filtering.
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/RisonQuery'
responses:
'200':
description: A page of dashboards.
content:
application/json:
schema:
$ref: '#/components/schemas/SupersetListResponse'
post:
operationId: createDashboard
tags:
- Dashboards
summary: Create a dashboard (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: The created dashboard.
/api/v1/dashboard/{pk}:
get:
operationId: getDashboard
tags:
- Dashboards
summary: Get a dashboard by id (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Pk'
responses:
'200':
description: A single dashboard.
'404':
description: Not found.
put:
operationId: updateDashboard
tags:
- Dashboards
summary: Update a dashboard (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Pk'
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The updated dashboard.
delete:
operationId: deleteDashboard
tags:
- Dashboards
summary: Delete a dashboard (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Pk'
responses:
'200':
description: Deleted.
/api/v1/chart/:
get:
operationId: getCharts
tags:
- Charts
summary: List charts (Superset proxy)
description: Per-workspace proxy to the Apache Superset Chart API.
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/RisonQuery'
responses:
'200':
description: A page of charts.
content:
application/json:
schema:
$ref: '#/components/schemas/SupersetListResponse'
post:
operationId: createChart
tags:
- Charts
summary: Create a chart (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: The created chart.
/api/v1/chart/{pk}:
get:
operationId: getChart
tags:
- Charts
summary: Get a chart by id (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Pk'
responses:
'200':
description: A single chart.
/api/v1/chart/data:
post:
operationId: getChartData
tags:
- Charts
summary: Query chart data (Superset proxy)
description: >-
Executes a chart data query and returns the result payload, the same
endpoint Superset uses to populate visualizations.
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: Chart data result.
/api/v1/dataset/:
get:
operationId: getDatasets
tags:
- Datasets
summary: List datasets (Superset proxy)
description: Per-workspace proxy to the Apache Superset Dataset API.
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/RisonQuery'
responses:
'200':
description: A page of datasets.
content:
application/json:
schema:
$ref: '#/components/schemas/SupersetListResponse'
post:
operationId: createDataset
tags:
- Datasets
summary: Create a dataset (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: The created dataset.
/api/v1/dataset/{pk}:
get:
operationId: getDataset
tags:
- Datasets
summary: Get a dataset by id (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Pk'
responses:
'200':
description: A single dataset.
/api/v1/database/:
get:
operationId: getDatabases
tags:
- Databases
summary: List database connections (Superset proxy)
description: Per-workspace proxy to the Apache Superset Database API.
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/RisonQuery'
responses:
'200':
description: A page of database connections.
content:
application/json:
schema:
$ref: '#/components/schemas/SupersetListResponse'
post:
operationId: createDatabase
tags:
- Databases
summary: Create a database connection (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'201':
description: The created database connection.
/api/v1/database/{pk}:
get:
operationId: getDatabase
tags:
- Databases
summary: Get a database connection by id (Superset proxy)
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/Pk'
responses:
'200':
description: A single database connection.
/api/v1/sqllab/execute/:
post:
operationId: executeSql
tags:
- SQL Lab
summary: Execute a SQL query (Superset proxy)
description: >-
Per-workspace proxy to the Apache Superset SQL Lab execute endpoint.
Runs an ad hoc SQL query against a connected database and returns the
result set or an async query id.
servers:
- url: https://{workspaceSlug}.{region}.app.preset.io
variables:
workspaceSlug:
default: my-workspace
region:
default: us2a
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SqlExecuteRequest'
responses:
'200':
description: Query results.
'202':
description: Async query accepted.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT obtained from POST /v1/auth/ by exchanging an API token name and
secret. Passed as Authorization: Bearer <token>.
parameters:
TeamName:
name: teamName
in: path
required: true
description: The team name (slug).
schema:
type: string
WorkspaceName:
name: workspaceName
in: path
required: true
description: The workspace name (slug).
schema:
type: string
Pk:
name: pk
in: path
required: true
description: The Superset object primary key (id).
schema:
type: integer
RisonQuery:
name: q
in: query
required: false
description: >-
Superset Rison/JSON-encoded query for filtering, ordering, and
pagination.
schema:
type: string
schemas:
AuthRequest:
type: object
required:
- name
- secret
properties:
name:
type: string
description: The API token name from Preset account settings.
secret:
type: string
description: The API token secret.
AuthResponse:
type: object
properties:
payload:
type: object
properties:
access_token:
type: string
description: The JWT access token used as a Bearer token.
Team:
type: object
properties:
id:
type: integer
name:
type: string
description: The team name (slug).
title:
type: string
TeamList:
type: object
properties:
payload:
type: array
items:
$ref: '#/components/schemas/Team'
Workspace:
type: object
properties:
id:
type: integer
name:
type: string
description: The workspace slug used in the proxy hostname.
title:
type: string
region:
type: string
description: The workspace region used in the proxy hostname.
hostname:
type: string
description: Fully qualified workspace hostname, e.g. my-workspace.us2a.app.preset.io.
WorkspaceList:
type: object
properties:
payload:
type: array
items:
$ref: '#/components/schemas/Workspace'
WorkspaceCreate:
type: object
required:
- title
properties:
title:
type: string
region:
type: string
GuestTokenRequest:
type: object
properties:
user:
type: object
description: Identity attributes for the guest user.
resources:
type: array
items:
type: object
description: The embedded resources (e.g. dashboard id) being granted.
rls:
type: array
items:
type: object
description: Row level security rules applied to the guest session.
GuestTokenResponse:
type: object
properties:
payload:
type: object
properties:
token:
type: string
description: The short-lived guest token.
SqlExecuteRequest:
type: object
required:
- database_id
- sql
properties:
database_id:
type: integer
sql:
type: string
schema:
type: string
runAsync:
type: boolean
SupersetListResponse:
type: object
properties:
count:
type: integer
ids:
type: array
items:
type: integer
result:
type: array
items:
type: object