Mode Datasets API

swagger: '2.0'
info:
  version: 0.0.1
  title: Mode Account Datasets 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: Datasets
paths:
  /{account}/datasets/{dataset}/fields:
    x-summary: Dataset Field Descriptions
    get:
      operationId: getDatasetFields
      summary: Get fields for a Dataset
      description: Returns a list of the latest fields for a `Dataset`
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      responses:
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '200':
          description: '`DatasetField` collection response'
          schema:
            $ref: '#/definitions/DatasetFields'
      tags:
      - Datasets
  /{account}/datasets/{dataset}/field_descriptions:
    x-summary: Dataset Field Descriptions
    get:
      operationId: getDatasetFieldDescriptions
      summary: Get field descriptions for a Dataset
      description: Returns a list of field descriptions for a `Dataset`
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      responses:
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '200':
          description: '`DatasetFieldDescriptions` collection response'
          schema:
            $ref: '#/definitions/DatasetFieldDescriptions'
      tags:
      - Datasets
    post:
      operationId: createDatasetFieldDescriptions
      summary: Create a field description for a Dataset
      description: Create a field description for a `Dataset` with the provided parameters
      parameters:
      - name: parameters
        in: body
        description: Dataset field description parameters
        required: true
        schema:
          $ref: '#/definitions/CreateDatasetFieldDescriptionBody'
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      responses:
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequest'
        '200':
          description: '`DatasetFieldDescription` response'
          schema:
            $ref: '#/definitions/DatasetFieldDescription'
      tags:
      - Datasets
  /{account}/datasets/{dataset}/field_descriptions/{field_description}:
    x-summary: Dataset Field Descriptions
    patch:
      operationId: updateDatasetFieldDescription
      summary: Update a field description for a Dataset
      description: Updates a field description for a `Dataset` with the provided parameters
      parameters:
      - name: parameters
        in: body
        description: Dataset field description parameters
        required: true
        schema:
          $ref: '#/definitions/UpdateDatasetFieldDescriptionBody'
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      - name: field description
        in: path
        description: '`DatasetFieldDescription` token'
        required: true
        type: string
      responses:
        '404':
          description: '`DatasetFieldDescription` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequest'
        '200':
          description: '`DatasetFieldDescription` response'
          schema:
            $ref: '#/definitions/DatasetFieldDescription'
      tags:
      - Datasets
    delete:
      operationId: deleteDatasetFieldDescription
      summary: Delete a field description for a Dataset
      description: Deletes a field description for a `Dataset`
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      - name: field description
        in: path
        description: '`DatasetFieldDescription` token'
        required: true
        type: string
      responses:
        '404':
          description: '`DatasetFieldDescription` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '200':
          description: '`DatasetFieldDescription` response'
          schema:
            $ref: '#/definitions/DatasetFieldDescription'
      tags:
      - Datasets
  /{account}/datasets/{dataset}:
    x-summary: Dataset
    patch:
      operationId: updateDataset
      summary: Update a Dataset
      description: Updates a single `Dataset` with the provided attributes
      parameters:
      - name: parameters
        in: body
        schema:
          $ref: '#/definitions/UpdateReportRequestBody'
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: '`Dataset` response'
          schema:
            $ref: '#/definitions/Report'
      tags:
      - Datasets
    get:
      operationId: getDataset
      summary: Get a Dataset
      description: Returns a representation of a single `Dataset`
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: '`Dataset` response'
          schema:
            $ref: '#/definitions/Report'
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      tags:
      - Datasets
    delete:
      operationId: deleteDataset
      summary: Delete a Dataset
      description: Deletes a single `Dataset`
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequest'
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: Empty body
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      tags:
      - Datasets
  /{account}/datasets/{dataset}/reports:
    x-summary: Dataset
    get:
      operationId: getDatasetReports
      summary: List Reports using a Dataset
      description: Returns a list of reports that have imported the `Dataset`
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '404':
          description: '`Dataset` 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: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      tags:
      - Datasets
  /{account}/datasets/{dataset}/runs:
    x-summary: Dataset Runs
    post:
      operationId: runDataset
      summary: Create a Dataset run
      description: Runs a single `Dataset` and returns a representation of the resulting `DatasetRun`
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      responses:
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequest'
        '202':
          description: '`DatasetRun` Accepted'
          schema:
            $ref: '#/definitions/DatasetRun'
      tags:
      - Datasets
    get:
      operationId: listDatasetRuns
      summary: List Dataset runs
      description: Returns a list of `DatasetRun`s for a `Dataset`
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      - name: filter
        in: query
        description: 'Returns a filtered list of `Run`s for a `Dataset` 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=updated_at.lt.2019-10-23T06:23:01Z` returns all `Runs` in a space created before that date.'
        required: false
        type: string
      - name: order
        in: query
        description: With the `order` param, returns all `DatasetRun`s for a `Dataset` ordered by their `created_at` or `updated_at` timestamps
        required: false
        type: string
      - name: order_by
        in: query
        description: With the `order_by` param, returns all `DatasetRun`s for a `Dataset` ordered in `asc` or `desc` order
        required: false
        type: string
      responses:
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '200':
          description: '`DatasetRun` collection response'
          schema:
            $ref: '#/definitions/ReportRuns'
      tags:
      - Datasets
  /{workspace}/datasets/{dataset}/schedules:
    x-summary: DatasetSchedules
    get:
      operationId: listDatasetSchedules
      summary: List schedules for a dataset
      description: Returns all `Schedule`s for a `Dataset`
      responses:
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '404':
          description: '`Dataset` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '200':
          description: Dataset `Schedule` collection response
          schema:
            $ref: '#/definitions/DatasetSchedules'
      parameters:
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      tags:
      - Datasets
  /{account}/datasets/{dataset}/runs/{run}:
    x-summary: Dataset Run
    get:
      operationId: getDatasetRun
      summary: Get a Dataset run
      description: Returns a representation of a single `DatasetRun`
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        type: string
      - name: dataset
        in: path
        description: '`Dataset` token'
        required: true
        type: string
      - name: run
        in: path
        description: '`DatasetRun` token'
        required: true
        type: string
      responses:
        '404':
          description: '`DatasetRun` not found'
          schema:
            $ref: '#/definitions/NotFound'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '200':
          description: '`DatasetRun` response'
          schema:
            $ref: '#/definitions/ReportRun'
      tags:
      - Datasets
definitions:
  Reports:
    properties:
      pagination:
        $ref: '#/definitions/Pagination'
      _links:
        $ref: '#/definitions/ReportsLinks'
      _embedded:
        $ref: '#/definitions/ReportsEmbeds'
    required:
    - _links
  UpdateReportRequestBody:
    required:
    - report
    type: object
    properties:
      report:
        type: object
        properties:
          name:
            type: string
            description: The name of the report
            example: Kanto Region Diaspora
          description:
            type: string
            description: A description of the report in question
            example: An analysis of all the creatures living in the region. Please contribute any missing data. Pocket version coming soon.
          space_token:
            type: string
            description: The token of the space this report will be moved to
            example: 5a4177a2902c
  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
  ReportRunsEmbeds: {}
  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
  DatasetRunLinks:
    properties:
      self:
        $ref: '#/definitions/Link'
      account:
        $ref: '#/definitions/Link'
      executed_by:
        $ref: '#/definitions/Link'
      latest_successful_dataset_run_api_url:
        $ref: '#/definitions/Link'
      dataset:
        $ref: '#/definitions/Link'
      query_runs:
        $ref: '#/definitions/Link'
      share:
        $ref: '#/definitions/Link'
    required:
    - self
    - account
    - dataset
    - query_runs
  ReportEmbeds: {}
  DatasetRun:
    properties:
      created_at:
        type: string
      completed_at:
        type: string
      is_latest_dataset_run:
        type: string
      is_latest_successful_dataset_run:
        type: string
      purge_completed_at:
        type: string
      purge_started_at:
        type: string
      dataset_has_failures_since_last_success:
        type: string
      state:
        enum:
        - pending
        - enqueued
        - cancelled
        - failed
        - succeeded
        - completed
        type: string
      token:
        type: string
      updated_at:
        type: string
      pusher_channel_name:
        type: string
      _links:
        $ref: '#/definitions/DatasetRunLinks'
      _embedded:
        $ref: '#/definitions/DatasetRunEmbeds'
    required:
    - _links
    - created_at
    - completed_at
    - is_latest_dataset_run
    - is_latest_successful_dataset_run
    - purge_completed_at
    - purge_started_at
    - dataset_has_failures_since_last_success
    - state
    - token
    - updated_at
  ReportRunsLinks:
    properties:
      next_page:
        $ref: '#/definitions/Link'
      prev_page:
        $ref: '#/definitions/Link'
      self:
        $ref: '#/definitions/Link'
    required:
    - self
  Unauthorized:
    required:
    - id
    - message
    properties:
      id:
        type: string
        enum:
        - unauthorized
      message:
        type: string
  ReportRunParameters: {}
  Report:
    properties:
      token:
        type: string
      id:
        type: integer
      name:
        type: string
      description:
        type: string
      created_at:
        type: string
      updated_at:
        type: string
      published_at:
        type: string
      edited_at:
        type: string
      theme_id:
        type: integer
      color_mappings:
        type: string
      type:
        type: string
      last_successful_sync_at:
        type: string
      last_saved_at:
        type: string
      archived:
        type: boolean
      space_token:
        type: string
      account_id:
        type: integer
      account_username:
        type: string
      public:
        type: boolean
      full_width:
        type: boolean
      manual_run_disabled:
        type: boolean
      drill_anywhere_enabled:
        type: boolean
      run_privately:
        type: boolean
      drilldowns_enabled:
        type: boolean
      layout:
        type: string
      is_embedded:
        type: boolean
      is_signed:
        type: boolean
      imported_datasets:
        type: string
      shared:
        type: boolean
      expected_runtime:
        type: number
      last_successfully_run_at:
        type: string
      last_run_at:
        type: string
      web_preview_image:
        type: string
      last_successful_run_token:
        type: string
      github_link:
        type: string
      query_count:
        type: string
      max_query_count:
        type: string
      chart_count:
        type: string
      runs_count:
        type: string
      schedules_count:
        type: string
      query_preview:
        type: string
      view_count:
        type: string
      thoughtspot_published_at:
        type: string
      _links:
        $ref: '#/definitions/ReportLinks'
      _embedded:
        $ref: '#/definitions/ReportEmbeds'
    required:
    - _links
    - token
    - id
    - name
    - created_at
    - updated_at
    - published_at
    - edited_at
    - type
    - last_successful_sync_at
    - last_saved_at
    - archived
    - account_id
    - account_username
    - public
    - manual_run_disabled
    - drill_anywhere_enabled
    - run_privately
    - drilldowns_enabled
    - expected_runtime
    - last_successfully_run_at
    - last_run_at
    - last_successful_run_token
    - query_count
    - max_query_count
    - runs_count
    - schedules_count
    - query_preview
    - view_count
    - thoughtspot_published_at
  ReportsEmbeds: {}
  ReportRunEmbeds: {}
  UpdateDatasetFieldDescriptionBody:
    required:
    - field_description
    type: object
    properties:
      field_description:
        type: object
        description: The parameters for updating the field description
        properties:
          desc:
            description: The description of the field
            type: string
  CreateDatasetFieldDescriptionBody:
    required:
    - field_description
    type: object
    properties:
      field_description:
        type: object
        description: The parameters for updating the field description
        properties:
          desc:
            description: The description of the field
            type: string
          name:
            description: The name of the field
            type: string
  NotFound:
    required:
    - id
    - message
    properties:
      id:
        type: string
        enum:
        - not_found
      message:
        type: string
  ReportsLinks:
    properties:
      next_page:
        $ref: '#/definitions/Link'
      prev_page:
        $ref: '#/definitions/Link'
      self:
        $ref: '#/definitions/Link'
    required:
    - self
  ReportRunLinks:
    properties:
      latest_successful_report_run_api_url:
        $ref: '#/definitions/Link'
      self:
        $ref: '#/definitions/Link'
      content:
        $ref: '#/definitions/Link'
      preview:
        $ref: '#/definitions/Link'
      account:
        $ref: '#/definitions/Link'
      report_schedule:
        $ref: '#/definitions/Link'
      executed_by:
        $ref: '#/definitions/Link'
      share:
        $ref: '#/definitions/Link'
      embed:
        $ref: '#/definitions/Link'
      report:
        $ref: '#/definitions/Link'
      clone:
        $ref: '#/definitions/Link'
      query_runs:
        $ref: '#/definitions/Link'
      python_cell_runs:
        $ref: '#/definitions/Link'
      pdf_export:
        $ref: '#/definitions/Link'
      web_edit_dataset:
        $ref: '#/definitions/Link'
      web_clone:
        $ref: '#/definitions/Link'
      web_external_url:
        $ref: '#/definitions/Link'
    required:
    - self
    - account
    - report
    - query_runs
  DatasetRunEmbeds: {}
  ReportLinks:
    properties:
      self:
        $ref: '#/definitions/Link'
      web:
        $ref: '#/definitions/Link'
      web_edit:
        $ref: '#/definitions/Link'
      web_external_url:
        $ref: '#/definitions/Link'
      csv_export:
        $ref: '#/definitions/Link'
      share:
        $ref: '#/definitions/Link'
      web_report_runs:
        $ref: '#/definitions/Link'
      account:
        $ref: '#/definitions/Link'
      report_run:
        $ref: '#/definitions/Link'
      star:
        $ref: '#/definitions/Link'
      space:
        $ref: '#/definitions/Link'
      space_links:
        $ref: '#/definitions/Link'
      queries:
        $ref: '#/definitions/Link'
      report_runs:
        $ref: '#/definitions/Link'
      report_pins:
        $ref: '#/definitions/Link'
      report_filters:
        $ref: '#/definitions/Link'
      report_schedules:
        $ref: '#/definitions/Link'
      report_subscriptions:
        $ref: '#/definitions/Link'
      dataset_dependencies:
        $ref: '#/definitions/Link'
      python_visualizations:
        $ref: '#/definitions/Link'
      embed_key:
        $ref: '#/definitions/Link'
      last_run:
        $ref: '#/definitions/Link'
      last_successful_run:
        $ref: '#/definitions/Link'
      python_notebook:
        $ref: '#/definitions/Link'
      perspective_email_subscription_memberships:
        $ref: '#/definitions/Link'
      validate_email_subscriber:
        $ref: '#/definitions/Link'
      creator:
        $ref: '#/definitions/Link'
      report_theme:
        $ref: '#/definitions/Link'
      last_successful_github_sync:
        $ref: '#/definitions/Link'
      report_index_web:
        $ref: '#/definitions/Link'
      dbt_metadata:
        $ref: '#/definitions/Link'
    required:
    - self
    - web
    - account
    - report_run
    - queries
    - report_runs
    - report_pins
    - report_schedules
    - last_run
    - last_successful_run
    - perspective_email_subscription_memberships
    - last_successful_github_sync
  ReportRuns:
    properties:
      pagination:
        $ref: '#/definitions/Pagination'
      _links:
        $ref: '#/definitions/ReportRunsLinks'
      _embedded:
        $ref: '#/definitions/ReportRunsEmbeds'
    required:
    - _links
  ReportRun:
    properties:
      token:
        type: string
      state:
        enum:
        - pending
        - enqueued
        - cancelled
        - failed
        - succeeded
        - completed
        - running_notebook
        type: string
      parameters:
        $ref: '#/definitions/ReportRunParameters'
      created_at:
        type: string
      updated_at:
        type: string
      completed_at:
        type: string
      purge_started_at:
        type: string
      purge_completed_at:
        type: string
      python_state:
        enum:
        - none
        - pending
        - failed
        - submitted
        - succeeded
        type: string
      form_fields:
        type: array
      is_latest_report_run:
        type: string
      is_latest_successful_report_run:
        type: string
      report_has_failures_since_last_success:
        type: string
      pusher_channel_name:
        type: string
      _links:
        $ref: '#/definitions/ReportRunLinks'
      _embedded:
        $ref: '#/definitions/ReportRunEmbeds'
    required:
    - _links
    - token
    - state
    - created_at
    - updated_at
    - completed_at
    - purge_started_at
    - purge_completed_at
    - is_latest_report_run
    - is_latest_successful_report_run
    - report_has_failures_since_last_success
securityDefinitions:
  accessTokenAuth:
    type: basic