Mode Spaces API

openapi: 3.2.0
info:
  version: 0.0.1
  title: Mode Account Spaces 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
servers:
- url: https://modeanalytics.com/api
security:
- accessTokenAuth: []
tags:
- name: Spaces
paths:
  /{account}/spaces/{space}/datasets:
    x-summary: Datasets
    get:
      operationId: listDatasetsInSpace
      summary: List Datasets for a space
      description: Returns all `Dataset`s in a `Space`
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: '`Dataset` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '200':
          description: '`Dataset` collection response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Datasets'
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        schema:
          type: string
      - name: space
        in: path
        description: '`Space` token'
        required: true
        schema:
          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
        schema:
          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
        schema:
          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
        schema:
          type: string
      tags:
      - Spaces
  /{account}/spaces/{space}/reports:
    x-summary: Reports
    get:
      operationId: listReportsInSpace
      summary: List reports for a space
      description: Returns all `Report`s in a `Space`
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: '`Report` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '200':
          description: '`Report` collection response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Reports'
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        schema:
          type: string
      - name: space
        in: path
        description: '`Space` token'
        required: true
        schema:
          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
        schema:
          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
        schema:
          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
        schema:
          type: string
      tags:
      - Spaces
  /{account}/spaces/{space}/memberships:
    x-summary: Space Memberships
    post:
      operationId: createSpaceMemberships
      summary: Create a space membership
      description: Returns all `Memberships` for a `Space`
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        schema:
          type: string
      - name: space
        in: path
        description: '`Space` token'
        required: true
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '400':
          description: Bad request
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '404':
          description: '`Space` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '200':
          description: '`SpaceMembership` response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/SpaceMembership'
      tags:
      - Spaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpaceMembershipRequestBody'
    get:
      operationId: listSpaceMemberships
      summary: List space memberships
      description: Returns all `Memberships` for a `Space`
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '400':
          description: Bad request
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '404':
          description: '`Space` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '200':
          description: '`SpaceMembership` collection response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/SpaceMemberships'
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        schema:
          type: string
      - name: space
        in: path
        description: '`Space` token'
        required: true
        schema:
          type: string
      tags:
      - Spaces
  /{account}/spaces/{space}/memberships/{space_membership}:
    x-summary: Space Membership
    get:
      operationId: getSpaceMembership
      summary: Get a space membership
      description: Returns a single `Membership` for a `Space`
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: '`Space Membership` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '200':
          description: '`SpaceMembership` response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/SpaceMembership'
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        schema:
          type: string
      - name: space
        in: path
        description: '`Space` token'
        required: true
        schema:
          type: string
      - name: space_membership
        in: path
        description: '`Space Membership` token'
        required: true
        schema:
          type: string
      tags:
      - Spaces
    delete:
      operationId: deleteSpaceMembership
      summary: Delete a space membership
      description: Delets a single `Membership` for a `Space`
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: '`Space Membership` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '200':
          description: '`SpaceMembership` response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/SpaceMembership'
      parameters:
      - name: account
        in: path
        description: '`Account` (`Workspace` or `User`) username'
        required: true
        schema:
          type: string
      - name: space
        in: path
        description: '`Space` token'
        required: true
        schema:
          type: string
      - name: space_membership
        in: path
        description: '`Space Membership` token'
        required: true
        schema:
          type: string
      tags:
      - Spaces
  /{workspace}/spaces:
    x-summary: Collection
    get:
      operationId: listCollections
      summary: List Collections
      description: Returns a representation of `Collection`s in a `Workspace` visible to the authenticated `User`
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: '`Workspace` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '200':
          description: '`Space` collection response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Spaces'
      parameters:
      - in: query
        name: filter
        description: 'Returns a filtered list of `Collection`s. Valid options include `all`. The default returns a list of `Collection`''s that do not include other user''s personal collections. Example: `?filter=all` returns all `Collections` including personal collections.'
        required: false
        schema:
          type: string
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        schema:
          type: string
      - name: page
        in: path
        description: Page of results
        required: true
        schema:
          type: integer
      - name: per_page
        in: path
        description: Results per page
        required: true
        schema:
          type: integer
      tags:
      - Spaces
    post:
      operationId: createCollection
      summary: Create a Collection
      description: Creates a `Collection`
      parameters:
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: '`Account` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '403':
          description: Forbidden
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '400':
          description: Bad request
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '200':
          description: '`Space` response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Space'
      tags:
      - Spaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateSpaceRequestBody'
  /{workspace}/spaces/{space}:
    x-summary: Collection
    get:
      operationId: getCollection
      summary: Get a Collection
      description: Returns a representation of a single `Collection`
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: '`Space` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '200':
          description: '`Space` response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Space'
      parameters:
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        schema:
          type: string
      - name: space
        in: path
        description: '`Space` token'
        required: true
        schema:
          type: string
      tags:
      - Spaces
    delete:
      operationId: deleteCollection
      summary: Delete a Collection
      description: Deletes a single `Collection`
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: '`Space` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '200':
          description: '`Space` response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Space'
      parameters:
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        schema:
          type: string
      - name: space
        in: path
        description: '`Space` token'
        required: true
        schema:
          type: string
      tags:
      - Spaces
    post:
      operationId: updateCollection
      summary: Update a Collection
      description: Updates a `Collection`
      parameters:
      - name: workspace
        in: path
        description: '`Workspace` username'
        required: true
        schema:
          type: string
      - name: space
        in: path
        description: '`Space` token'
        required: true
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: '`Space` not found'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '403':
          description: Forbidden
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '400':
          description: Bad request
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '200':
          description: '`Space` response'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Space'
      tags:
      - Spaces
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateSpaceRequestBody'
components:
  schemas:
    BadRequest:
      required:
      - id
      - message
      properties:
        id:
          type: string
          enum:
          - bad_request
        message:
          type: string
    CreateSpaceMembershipRequestBody:
      required:
      - membership
      type: object
      properties:
        membership:
          required:
          - member_type
          - member_token
          type: object
          description: The attributes of the new member being added to the space
          properties:
            member_type:
              type: string
              description: The type of member, either `"User"` or `"UserGroup"`
              example: User
            member_token:
              type: string
              description: The token of the member being added
              example: 2bd8236f8ae4
    SpacesEmbeds: {}
    CreateOrUpdateSpaceRequestBody:
      required:
      - space
      type: object
      properties:
        space:
          required:
          - name
          type: object
          description: The parameters of the new or updated space
          properties:
            description:
              type: string
              description: Description of the `space`
            name:
              type: string
              description: Name of the `space`
    SpaceMembershipEmbeds: {}
    SpaceMembershipLinks:
      properties:
        self:
          $ref: '#/components/schemas/Link'
        member:
          $ref: '#/components/schemas/Link'
        creator:
          $ref: '#/components/schemas/Link'
      required:
      - self
      - member
    Unauthorized:
      required:
      - id
      - message
      properties:
        id:
          type: string
          enum:
          - unauthorized
        message:
          type: string
    Spaces:
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        _links:
          $ref: '#/components/schemas/SpacesLinks'
        _embedded:
          $ref: '#/components/schemas/SpacesEmbeds'
      required:
      - _links
    SpaceEmbeds: {}
    SpaceMembershipsLinks:
      properties:
        next_page:
          $ref: '#/components/schemas/Link'
        prev_page:
          $ref: '#/components/schemas/Link'
        self:
          $ref: '#/components/schemas/Link'
      required:
      - self
    Reports:
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        _links:
          $ref: '#/components/schemas/ReportsLinks'
        _embedded:
          $ref: '#/components/schemas/ReportsEmbeds'
      required:
      - _links
    SpaceMembershipsEmbeds: {}
    SpacesLinks:
      properties:
        next_page:
          $ref: '#/components/schemas/Link'
        prev_page:
          $ref: '#/components/schemas/Link'
        self:
          $ref: '#/components/schemas/Link'
      required:
      - self
    ReportsLinks:
      properties:
        next_page:
          $ref: '#/components/schemas/Link'
        prev_page:
          $ref: '#/components/schemas/Link'
        self:
          $ref: '#/components/schemas/Link'
      required:
      - self
    SpaceLinks:
      properties:
        self:
          $ref: '#/components/schemas/Link'
        detail:
          $ref: '#/components/schemas/Link'
        space_report_pins:
          $ref: '#/components/schemas/Link'
        web:
          $ref: '#/components/schemas/Link'
        reports:
          $ref: '#/components/schemas/Link'
        creator:
          $ref: '#/components/schemas/Link'
        user_space_membership:
          $ref: '#/components/schemas/Link'
        space_memberships:
          $ref: '#/components/schemas/Link'
        preview_space_memberships:
          $ref: '#/components/schemas/Link'
        search_space_permissions:
          $ref: '#/components/schemas/Link'
        viewed:
          $ref: '#/components/schemas/Link'
      required:
      - self
      - detail
      - reports
      - search_space_permissions
    NotFound:
      required:
      - id
      - message
      properties:
        id:
          type: string
          enum:
          - not_found
        message:
          type: string
    Link:
      required:
      - href
      properties:
        href:
          type: string
        templated:
          type: boolean
          default: false
    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
    ReportsEmbeds: {}
    SpaceMembership:
      properties:
        token:
          type: string
        member_token:
          type: string
        member_type:
          type: string
        member_id:
          type: string
        email:
          type: string
        _links:
          $ref: '#/components/schemas/SpaceMembershipLinks'
        _embedded:
          $ref: '#/components/schemas/SpaceMembershipEmbeds'
      required:
      - _links
      - token
      - member_token
      - member_type
      - member_id
    Forbidden:
      required:
      - id
      - message
      properties:
        id:
          type: string
          enum:
          - forbidden
        message:
          type: string
    SpaceMemberships:
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        _links:
          $ref: '#/components/schemas/SpaceMembershipsLinks'
        _embedded:
          $ref: '#/components/schemas/SpaceMembershipsEmbeds'
      required:
      - _links
    Space:
      properties:
        token:
          type: string
        id:
          type: integer
        space_type:
          type: string
        name:
          type: string
        description:
          type: string
        state:
          type: string
        restricted:
          type: boolean
        free_default:
          type: string
        viewable?:
          type: string
        viewed?:
          type: string
        default_access_level:
          type: string
        _links:
          $ref: '#/components/schemas/SpaceLinks'
        _embedded:
          $ref: '#/components/schemas/SpaceEmbeds'
      required:
      - _links
      - token
      - id
      - space_type
      - name
      - description
      - state
      - restricted
      - free_default
      - viewable?
  securitySchemes:
    accessTokenAuth:
      type: http
      scheme: basic