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