Mode Data Sources API

swagger: '2.0'
info:
  version: 0.0.1
  title: Mode Account Data Sources API
  description: 'Mode provides a REST API for many common operations, such as:


    * Listing spaces and reports

    * Running reports

    * Downloading query results


    ## Authentication


    For most Mode API calls, the client must supply an API token and secret for

    HTTP basic authentication.


    If authentication is required for a given resource, unauthenticated requests

    will result in a `401 Unauthorized` response.


    [Create and Manage API Tokens](https://modeanalytics.com/settings/access_tokens)

    '
  termsOfService: https://mode.com/tos/
  contact:
    name: Mode API Team
    email: support@modeanalytics.com
  license:
    name: MIT
host: modeanalytics.com
basePath: /api
schemes:
- https
consumes:
- application/json
produces:
- application/hal+json
security:
- accessTokenAuth: []
tags:
- name: Data Sources
paths:
  /{account}/data_sources/{data_source}/datasets:
    x-summary: Datasets
    get:
      operationId: listDatasetsUsingDataSource
      summary: List Datasets using a data source
      description: Returns all `Dataset`s using a `DataSource`
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: '`Dataset` collection response'
          schema:
            $ref: '#/definitions/Datasets'
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: data_source
        in: path
        description: '`DataSource` token'
        required: true
        type: string
      - name: filter
        in: query
        description: 'Returns a filtered list of `Dataset`s in a `Space` filtered by whether their `created_at` or `updated_at` timestamps are `gt` (greater than) or `lt` (less than) the datetime passed in ISO8601 format. Example: `?filter=created_at.gt.2019-10-23T06:23:01Z` returns all `Datasets` in a space created after that date.'
        required: false
        type: string
      - name: order
        in: query
        description: 'With the `order` param, returns all `Dataset`s in a `Space` ordered in `asc` or `desc` order. Example: `?order=asc&order_by=created_at`'
        required: false
        type: string
      - name: order_by
        in: query
        description: 'With the `order_by` param, returns all `Dataset`s in a `Space` ordered by their `created_at` or `updated_at` timestamps. Example: `?order_by=created_at&order=asc`'
        required: false
        type: string
      tags:
      - Data Sources
  /{account}/data_sources/{data_source}/schema_updates:
    x-summary: DataSources
    post:
      operationId: createDataSourceSchemaUpdate
      summary: Update data source schema
      description: Creates and queues a `schema update` for a `data source`
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequest'
        '404':
          description: '`DataSource` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: '`DataSourceSchemaUpdate` response'
          schema:
            $ref: '#/definitions/DataSourceSchemaUpdate'
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: data_source
        in: path
        description: '`DataSource` token'
        required: true
        type: string
      tags:
      - Data Sources
  /{workspace}/data_sources:
    x-summary: DataSources
    get:
      operationId: listDataSources
      summary: List data sources
      description: Returns all `DataSource`s owned by a `Workspace`
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '404':
          description: '`Workspace` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: '`DataSource` collection response'
          schema:
            $ref: '#/definitions/DataSources'
      parameters:
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        type: string
      tags:
      - Data Sources
  /{workspace}/data_sources/{data_source}:
    x-summary: Data Source
    get:
      operationId: getDataSource
      summary: Get a data source
      description: Returns a single `DataSource`
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '404':
          description: '`DataSource` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: '`DataSource` response'
          schema:
            $ref: '#/definitions/DataSource'
      parameters:
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        type: string
      - name: data_source
        in: path
        description: '`DataSource` token'
        required: true
        type: string
      tags:
      - Data Sources
    patch:
      operationId: updateDataSource
      summary: Update a data source
      description: Updates a `DataSource`
      parameters:
      - name: parameters
        in: body
        schema:
          $ref: '#/definitions/UpdateDataSourceRequestBody'
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        type: string
      - name: data_source
        in: path
        description: '`DataSource` token'
        required: true
        type: string
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequest'
        '404':
          description: '`DataSource` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: '`DataSource` response'
          schema:
            $ref: '#/definitions/DataSource'
      tags:
      - Data Sources
  /{workspace}/data_sources/{data_source}/purge:
    x-summary: Data Source
    post:
      operationId: purgeForDataSource
      summary: Purge report results
      description: Removes all report results that use a data source
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequest'
        '404':
          description: '`DataSource` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '202':
          description: Accepted
          schema: {}
      parameters:
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        type: string
      - name: data_source
        in: path
        description: '`DataSource` token'
        required: true
        type: string
      tags:
      - Data Sources
  /{account}/data_sources/{data_source}/reports:
    x-summary: Reports
    get:
      operationId: listReportsUsingDataSource
      summary: List reports using a data source
      description: Returns all `Report`s using a `DataSource`
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '404':
          description: '`Report` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: '`Report` collection response'
          schema:
            $ref: '#/definitions/Reports'
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: data_source
        in: path
        description: '`DataSource` token'
        required: true
        type: string
      - name: filter
        in: query
        description: 'Returns a filtered list of `Report`s in a `Space` filtered by whether their `created_at` or `updated_at` timestamps are `gt` (greater than) or `lt` (less than) the datetime passed in ISO8601 format. Example: `?filter=created_at.gt.2019-10-23T06:23:01Z` returns all `Reports` in a space created after that date.'
        required: false
        type: string
      - name: order
        in: query
        description: 'With the `order` param, returns all `Report`s in a `Space` ordered in `asc` or `desc` order. Example: `?order=asc&order_by=created_at`'
        required: false
        type: string
      - name: order_by
        in: query
        description: 'With the `order_by` param, returns all `Report`s in a `Space` ordered by their `created_at` or `updated_at` timestamps. Example: `?order_by=created_at&order=asc`'
        required: false
        type: string
      tags:
      - Data Sources
definitions:
  UpdateDataSourceRequestBody:
    required:
    - data_source
    type: object
    properties:
      data_source:
        type: object
        description: The parameters of the data source to update
        properties:
          name:
            type: string
            description: Name of the `data source`
            example: Redshift Database
          description:
            type: string
            description: Description of the `data source`
            example: Marketing data
          password:
            type: string
            description: Password for the `data source`
            example: redshift_db_pw
          custom_attributes:
            type: object
            description: For Oracle Autonomous Database connected via bridge, pass the connection string as a custom attribute
            properties:
              connection_string:
                type: string
          certificate:
            type: file
          key:
            type: file
          wallet:
            type: file
  Reports:
    properties:
      pagination:
        $ref: '#/definitions/Pagination'
      _links:
        $ref: '#/definitions/ReportsLinks'
      _embedded:
        $ref: '#/definitions/ReportsEmbeds'
    required:
    - _links
  DataSourcesLinks:
    properties:
      next_page:
        $ref: '#/definitions/Link'
      prev_page:
        $ref: '#/definitions/Link'
      self:
        $ref: '#/definitions/Link'
    required:
    - self
  Link:
    required:
    - href
    properties:
      href:
        type: string
      templated:
        type: boolean
        default: false
  BadRequest:
    required:
    - id
    - message
    properties:
      id:
        type: string
        enum:
        - bad_request
      message:
        type: string
  DataSourcesEmbeds: {}
  DataSourceSchemaUpdateEmbeds: {}
  Pagination:
    required:
    - first_page
    - last_page
    - total_pages
    - total_count
    properties:
      first_page:
        type: string
      last_page:
        type: string
      total_pages:
        type: integer
      total_count:
        type: integer
  Unauthorized:
    required:
    - id
    - message
    properties:
      id:
        type: string
        enum:
        - unauthorized
      message:
        type: string
  ReportsEmbeds: {}
  DataSources:
    properties:
      pagination:
        $ref: '#/definitions/Pagination'
      data_index_auth_token:
        type: string
      _links:
        $ref: '#/definitions/DataSourcesLinks'
      _embedded:
        $ref: '#/definitions/DataSourcesEmbeds'
    required:
    - _links
  NotFound:
    required:
    - id
    - message
    properties:
      id:
        type: string
        enum:
        - not_found
      message:
        type: string
  DataSourceLinks:
    properties:
      self:
        $ref: '#/definitions/Link'
      creator:
        $ref: '#/definitions/Link'
      account:
        $ref: '#/definitions/Link'
      permissions:
        $ref: '#/definitions/Link'
      web:
        $ref: '#/definitions/Link'
      web_home:
        $ref: '#/definitions/Link'
    required:
    - self
    - creator
    - account
    - web
    - web_home
  DataSourceSchemaUpdateLinks:
    properties:
      self:
        $ref: '#/definitions/Link'
    required:
    - self
  ReportsLinks:
    properties:
      next_page:
        $ref: '#/definitions/Link'
      prev_page:
        $ref: '#/definitions/Link'
      self:
        $ref: '#/definitions/Link'
    required:
    - self
  DataSourceEmbeds: {}
  DataSourceSchemaUpdate:
    properties:
      id:
        type: string
      token:
        type: string
      state:
        type: string
      content_length:
        type: string
      number_of_schemas:
        type: string
      number_of_tables:
        type: string
      last_succesful_refresh_at:
        type: string
      webapp_uri:
        type: string
      _links:
        $ref: '#/definitions/DataSourceSchemaUpdateLinks'
      _embedded:
        $ref: '#/definitions/DataSourceSchemaUpdateEmbeds'
    required:
    - _links
    - id
    - token
    - state
    - content_length
    - number_of_schemas
    - number_of_tables
  DataSource:
    properties:
      id:
        type: integer
      name:
        type: string
      description:
        type: string
      token:
        type: string
      adapter:
        enum:
        - jdbc:athena
        - jdbc:bigquery
        - jdbc:databricks
        - jdbc:dbtmetrics
        - jdbc:denodo
        - jdbc:druid
        - jdbc:hive
        - jdbc:impala
        - jdbc:mysql
        - jdbc:oracle
        - jdbc:oracleadb
        - jdbc:postgresql
        - jdbc:trino
        - jdbc:presto
        - jdbc:clickhouse
        - jdbc:redshift
        - jdbc:snowflake
        - jdbc:spark
        - jdbc:sqlserver
        - jdbc:treasuredata
        - jdbc:vertica
        - jdbc:salesforce
        - jdbc:dbtsemanticlayer
        - jdbc:looker
        - jdbc:arrowflightsql
        - jdbc:modedatasets
        type: string
      created_at:
        type: string
      updated_at:
        type: string
      has_expensive_schema_updates:
        type: boolean
      public:
        type: boolean
      asleep:
        type: boolean
      queryable:
        type: boolean
      soft_deleted:
        type: boolean
      display_name:
        type: string
      account_id:
        type: integer
      account_username:
        type: string
      organization_token:
        type: string
      organization_plan_code:
        type: string
      database:
        type: string
      host:
        type: string
      port:
        type: string
      ssl:
        type: boolean
      username:
        type: string
      provider:
        type: string
      vendor:
        type: string
      ldap:
        type: boolean
      warehouse:
        type: string
      bridged:
        type: boolean
      adapter_version:
        type: string
      custom_attributes:
        $ref: '#/definitions/DataSourceCustomAttributes'
      ssl_trusted_cert:
        type: string
      default_access_level:
        type: string
      _links:
        $ref: '#/definitions/DataSourceLinks'
      _embedded:
        $ref: '#/definitions/DataSourceEmbeds'
    required:
    - _links
    - id
    - name
    - description
    - token
    - adapter
    - created_at
    - updated_at
    - has_expensive_schema_updates
    - public
    - asleep
    - queryable
    - soft_deleted
    - display_name
    - database
    - host
    - port
    - ssl
    - username
    - provider
    - vendor
    - ldap
    - warehouse
    - bridged
    - adapter_version
    - custom_attributes
  DataSourceCustomAttributes:
    properties:
      standard_sql:
        type: boolean
securityDefinitions:
  accessTokenAuth:
    type: basic