openapi: 3.0.3
info:
  title: Losant Application Data and Data Tables API
  version: 1.29.4
  description: Manage Losant Applications, the top-level container for IoT solutions, plus dashboards, events, webhooks, integrations, files, audit logs, credentials, certificates, application keys, API tokens, and resource jobs. Derived from the Losant Platform API (Bravado/Swagger 2) at https://api.losant.com/.
  contact:
    name: Losant Support
    url: https://www.losant.com/contact
    email: hello@losant.com
  license:
    name: Proprietary
    url: https://www.losant.com/legal
  x-source: https://api.losant.com/
  x-publisher: Losant IoT, Inc.
servers:
- url: https://api.losant.com
  description: Losant Platform API (US multi-tenant cloud)
security:
- BearerAuth: []
tags:
- name: Data and Data Tables
  description: Data and Data Tables resources on the Losant Platform.
paths:
  /applications/{applicationId}/data-tables/{dataTableId}/rows/{rowId}:
    get:
      summary: Retrieves the Data Table Row
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: dataTableId
        in: path
        description: ID associated with the data table
        required: true
        example: 575ed78e7ae143cd83dc4aab
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: rowId
        in: path
        description: ID associated with the data table row
        required: true
        example: 596f832b128eda5cfe765443
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      responses:
        '200':
          description: Data table row information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataTableRow'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if data table row was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    patch:
      summary: Updates the Data Table Row
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: dataTableId
        in: path
        description: ID associated with the data table
        required: true
        example: 575ed78e7ae143cd83dc4aab
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: rowId
        in: path
        description: ID associated with the data table row
        required: true
        example: 596f832b128eda5cfe765443
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      requestBody:
        description: Object containing updated properties for the data table row
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dataTableRowInsertUpdate'
      responses:
        '200':
          description: Updated data table row information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataTableRow'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if data table row was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    delete:
      summary: Deletes a Data Table Row
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: dataTableId
        in: path
        description: ID associated with the data table
        required: true
        example: 575ed78e7ae143cd83dc4aab
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: rowId
        in: path
        description: ID associated with the data table row
        required: true
        example: 596f832b128eda5cfe765443
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      responses:
        '200':
          description: If data table row was successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if data table row was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
  /applications/{applicationId}/data-tables/{dataTableId}/rows:
    get:
      summary: Returns the Rows for a Data Table
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: dataTableId
        in: path
        description: ID associated with the data table
        required: true
        example: 575ed78e7ae143cd83dc4aab
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: sortColumn
        in: query
        description: Column to sort the rows by
        required: false
        example: myColumnName
        schema:
          type: string
      - name: sortDirection
        in: query
        description: Direction to sort the rows by
        required: false
        example: asc
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: limit
        in: query
        description: How many rows to return
        required: false
        example: 0
        schema:
          type: string
          default: 1000
      - name: offset
        in: query
        description: How many rows to skip
        required: false
        example: 0
        schema:
          type: string
          default: 0
      - name: includeFields
        in: query
        description: Comma-separated list of fields to include in resulting rows. When not provided, returns all fields.
        required: false
        example: id,createdAt
        schema:
          type: string
      responses:
        '200':
          description: Collection of data table rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataTableRows'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if data table was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    post:
      summary: Delete All Data in the Data Table
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: dataTableId
        in: path
        description: ID associated with the data table
        required: true
        example: 575ed78e7ae143cd83dc4aab
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      responses:
        '200':
          description: If request successfully deleted **all** rows in the data table, this will **not** send workflow data table deletion triggers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if data table was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
  /applications/{applicationId}/data-tables/{dataTableId}:
    get:
      summary: Retrieves Information on a Data Table
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: dataTableId
        in: path
        description: ID associated with the data table
        required: true
        example: 575ed78e7ae143cd83dc4aab
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      responses:
        '200':
          description: Data table information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataTable'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if data table was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    patch:
      summary: Updates Information About a Data Table
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: dataTableId
        in: path
        description: ID associated with the data table
        required: true
        example: 575ed78e7ae143cd83dc4aab
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      requestBody:
        description: Object containing updated properties of the data table
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dataTablePatch'
      responses:
        '200':
          description: Updated data table information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataTable'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if data table was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    post:
      summary: Adds a New Column to This Data Table
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: dataTableId
        in: path
        description: ID associated with the data table
        required: true
        example: 575ed78e7ae143cd83dc4aab
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      requestBody:
        description: Object containing the new column properties
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dataTableColumn'
      responses:
        '200':
          description: Updated data table information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataTable'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if data table was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    delete:
      summary: Deletes a Data Table
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: dataTableId
        in: path
        description: ID associated with the data table
        required: true
        example: 575ed78e7ae143cd83dc4aab
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      responses:
        '200':
          description: If data table was successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if data table was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
  /applications/{applicationId}/data-tables:
    get:
      summary: Returns the Data Tables for an Application
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: sortField
        in: query
        description: Field to sort the results by
        required: false
        example: name
        schema:
          type: string
          enum:
          - name
          - id
          - creationDate
          - lastUpdated
          default: name
      - name: sortDirection
        in: query
        description: Direction to sort the results by
        required: false
        example: asc
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: page
        in: query
        description: Which page of results to return
        required: false
        example: 0
        schema:
          type: string
          default: 0
      - name: perPage
        in: query
        description: How many items to return per page
        required: false
        example: 10
        schema:
          type: string
          default: 100
      - name: filterField
        in: query
        description: Field to filter the results by. Blank or not provided means no filtering.
        required: false
        example: name
        schema:
          type: string
          enum:
          - name
      - name: filter
        in: query
        description: Filter to apply against the filtered field. Supports globbing. Blank or not provided means no filtering.
        required: false
        example: my*table
        schema:
          type: string
      responses:
        '200':
          description: Collection of data tables
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataTables'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if application was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    post:
      summary: Create a New Data Table for an Application
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      requestBody:
        description: New data table information
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dataTablePost'
      responses:
        '201':
          description: Successfully created data table
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataTable'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if application was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
  /applications/{applicationId}/data:
    post:
      summary: Creates a CSV File from a Query of Devices and Attributes Over a Time Range.
      tags:
      - Data and Data Tables
      parameters:
      - name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      requestBody:
        description: The query parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/devicesDataExport'
      responses:
        '202':
          description: If command was successfully sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobEnqueuedResult'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if application was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
components:
  schemas:
    dataTablePost:
      title: Data Table Post
      description: Schema for the body of a Data Table creation request
      type: object
      properties:
        name:
          $ref: '#/components/schemas/common/name'
        description:
          $ref: '#/components/schemas/common/description'
        columns:
          $ref: '#/components/schemas/dataTable/properties/columns'
      required:
      - name
      additionalProperties: false
    devicesDataExport:
      title: Devices Data Export
      description: Schema for exporting the data for multiple devices
      type: object
      properties:
        email:
          $ref: '#/components/schemas/common/email'
        callbackUrl:
          $ref: '#/components/schemas/common/url'
        deviceIds:
          $ref: '#/components/schemas/common/objectIds'
        deviceTags:
          $ref: '#/components/schemas/common/tagsOptional'
        deviceQuery:
          $ref: '#/components/schemas/advancedDeviceQuery'
        attributes:
          type: array
          maxItems: 256
          items:
            $ref: '#/components/schemas/common/key'
        start:
          type: number
        end:
          type: number
        options:
          type: object
          properties:
            includeDate:
              type: boolean
              default: true
            includeID:
              type: boolean
              default: true
            includeBlobData:
              type: boolean
              default: false
            filePerDevice:
              type: boolean
              default: false
      additionalProperties: false
    dataTables:
      title: Data Tables
      description: Schema for a collection of Data Tables
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/dataTable'
        count:
          type: integer
        totalCount:
          type: integer
        perPage:
          type: integer
        page:
          type: integer
        filter:
          type: string
        filterField:
          type: string
        sortField:
          type: string
        sortDirection:
          $ref: '#/components/schemas/common/sortDirection'
        applicationId:
          $ref: '#/components/schemas/common/objectId'
    dataTableRowInsertUpdate:
      title: Data Table Row Insert Update
      description: Schema for inserting or updating a data table row
      type: object
      patternProperties:
        ^[0-9a-zA-Z_-]{1,255}$:
          type:
          - string
          - number
          - boolean
          - 'null'
      additionalProperties: false
    dataTable:
      title: Data Table
      description: Schema for a single Data Table
      type: object
      properties:
        id:
          $ref: '#/components/schemas/common/objectId'
        dataTableId:
          $ref: '#/components/schemas/common/objectId'
        applicationId:
          $ref: '#/components/schemas/common/objectId'
        creationDate:
          $ref: '#/components/schemas/common/date'
        lastUpdated:
          $ref: '#/components/schemas/common/date'
        name:
          $ref: '#/components/schemas/common/name'
        description:
          $ref: '#/components/schemas/common/description'
        columns:
          type: array
          items:
            $ref: '#/components/schemas/dataTableColumn'
          maxItems: 50
    dataTableColumn:
      title: Data Table Column
      description: Schema for a single Data Table Column
      type: object
      properties:
        name:
          $ref: '#/components/schemas/common/key'
        dataType:
          type: string
          enum:
          - string
          - number
          - boolean
        constraint:
          type: string
          enum:
          - unique
          - required
          - optional
        defaultValue:
          type:
          - string
          - number
          - boolean
      required:
      - name
      - dataType
      - constraint
      additionalProperties: false
    dataTablePatch:
      title: Data Table Patch
      description: Schema for the body of a Data Table modification request
      type: object
      properties:
        name:
          $ref: '#/components/schemas/common/name'
        description:
          $ref: '#/components/schemas/common/description'
      additionalProperties: false
    dataTableRows:
      title: Data Table Rows
      description: Schema for a collection of Data Table Rows
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/dataTableRow'
        count:
          type: integer
        totalCount:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        sortColumn:
          type: string
        sortDirection:
          $ref: '#/components/schemas/common/sortDirection'
        dataTableId:
          $ref: '#/components/schemas/common/objectId'
        applicationId:
          $ref: '#/components/schemas/common/objectId'
        query:
          type: object
    advancedDeviceQuery:
      title: Advanced Device Query
      description: Schema for advanced device queries
      type: object
      properties:
        $and:
          type: array
          items:
            $ref: '#/components/schemas/advancedDeviceQuery'
          maxItems: 100
        $or:
          type: array
          items:
            $ref: '#/components/schemas/advancedDeviceQuery'
          maxItems: 100
        $nor:
          type: array
          items:
            $ref: '#/components/schemas/advancedDeviceQuery'
          maxItems: 100
        id:
          $ref: '#/components/schemas/common/advancedIdQuery'
        creationDate:
          $ref: '#/components/schemas/common/advancedValueQuery'
        lastUpdated:
          $ref: '#/components/schemas/common/advancedValueQuery'
        deletedAt:
          $ref: '#/components/schemas/common/advancedValueQuery'
        name:
          $ref: '#/components/schemas/common/advancedValueQuery'
        deviceClass:
          $ref: '#/components/schemas/common/advancedValueQuery'
        gatewayId:
          $ref: '#/components/schemas/common/advancedIdQuery'
        parentId:
          $ref: '#/components/schemas/common/advancedIdQuery'
        ancestorId:
          $ref: '#/components/schemas/common/advancedIdQuery'
        attributeName:
          $ref: '#/components/schemas/common/advancedValueQuery'
        experienceUserId:
          $ref: '#/components/schemas/common/advancedIdQuery'
        experienceGroupId:
          $ref: '#/components/schemas/common/advancedIdQuery'
        tags:
          $ref: '#/components/schemas/common/advancedTagQueryWithOps'
        disconnectedAt:
          $ref: '#/components/schemas/common/advancedValueQuery'
        connectedAt:
          $ref: '#/components/schemas/common/advancedValueQuery'
        connectionStatus:
          $ref: '#/components/schemas/common/advancedValueQuery'
      additionalProperties: false
    success:
      title: Success
      description: Schema for reporting a successful operation
      type: object
      properties:
        success:
          type: boolean
          enum:
          - true
    error:
      title: Error
      description: Schema for errors returned by the API
      type: object
      properties:
        type:
          type: string
        message:
          type: string
    jobEnqueuedResult:
      title: Job Enqueued API Result
      description: Schema for the result of a job being queued
      type: object
      properties:
        jobQueued:
          type: boolean
          enum:
          - true
        jobId:
          type: string
          maxLength: 21
        success:
          type: boolean
          enum:
          - true
    dataTableRow:
      title: Data Table Row
      description: Schema for a single Data Table Row
      type: object
      properties:
        id:
          $ref: '#/components/schemas/common/objectId'
        createdAt:
          $ref: '#/components/schemas/common/date'
        updatedAt:
          $ref: '#/components/schemas/common/date'
      patternProperties:
        ^[0-9a-zA-Z_-]{1,255}$:
          type:
          - string
          - number
          - boolean
          - 'null'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Losant uses JSON Web Tokens (JWTs) for authentication. Obtain a token via POST /auth/user, POST /auth/device, POST /applications/{applicationId}/tokens, or POST /me/tokens and pass it in the Authorization header as `Bearer <token>`.