Losant Device API

openapi: 3.0.3
info:
  title: Losant Device API
  version: 1.29.4
  description: Provision, manage, query, and send commands to IoT devices and device recipes. Read device state, attributes,
    connection status, logs, and tag-based queries. 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)
tags:
- name: Device
  description: Device resources on the Losant Platform.
security:
- BearerAuth: []
paths:
  /applications/{applicationId}/devices/{deviceId}/attributes/{name}:
    get:
      summary: Retrieves Information on a Device Attribute
      tags:
      - Device
      parameters:
      - &id001
        name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - &id002
        name: deviceId
        in: path
        description: ID associated with the device
        required: true
        example: 575ecf887ae143cd83dc4aa2
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - &id003
        name: name
        in: path
        description: Name of the attribute
        required: true
        example: voltage
        schema:
          type: string
          pattern: ^[0-9a-zA-Z_-]{1,255}$
      responses:
        '200':
          description: Device attribute information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceAttribute'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if device attribute was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    patch:
      summary: Updates an Attribute on a Device
      tags:
      - Device
      parameters:
      - *id001
      - *id002
      - *id003
      requestBody:
        description: Object containing new properties of the device attribute
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceAttributePatch'
      responses:
        '200':
          description: Updated device attribute information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceAttribute'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if device attribute was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    delete:
      summary: Removes an Attribute from a Device
      tags:
      - Device
      parameters:
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: If device attribute 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 device attribute was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
  /applications/{applicationId}/devices/{deviceId}/attributes:
    get:
      summary: Returns the Attributes for a Device
      tags:
      - Device
      parameters:
      - &id004
        name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - &id005
        name: deviceId
        in: path
        description: ID associated with the device
        required: true
        example: 575ecf887ae143cd83dc4aa2
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: sortField
        in: query
        description: Field to sort the results by
        required: false
        example: status
        schema:
          type: string
          enum:
          - name
          - dataType
          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: filterField
        in: query
        description: Field to filter the results by. Blank or not provided means no filtering.
        required: false
        example: status
        schema:
          type: string
          enum:
          - name
          - dataType
      - name: filter
        in: query
        description: Filter to apply against the filtered field. Supports globbing. Blank or not provided means no filtering.
        required: false
        example: number
        schema:
          type: string
      responses:
        '200':
          description: Collection of device attributes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceAttributes'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if device was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    post:
      summary: Adds a New Attribute to a Device
      tags:
      - Device
      parameters:
      - *id004
      - *id005
      requestBody:
        description: Device attribute information
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceAttributePost'
      responses:
        '201':
          description: Successfully created device attribute
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceAttribute'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if device was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
  /applications/{applicationId}/device-recipes/{deviceRecipeId}:
    get:
      summary: Retrieves Information on a Device Recipe
      tags:
      - Device
      parameters:
      - &id006
        name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - &id007
        name: deviceRecipeId
        in: path
        description: ID associated with the device recipe
        required: true
        example: 575ecec57ae143cd83dc4a9f
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: tagsAsObject
        in: query
        description: Return tags as an object map instead of an array
        required: false
        example: true
        schema:
          type: string
      - name: attributesAsObject
        in: query
        description: Return attributes as an object map instead of an array
        required: false
        example: true
        schema:
          type: string
      responses:
        '200':
          description: Device recipe information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceRecipe'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if device recipe was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    patch:
      summary: Updates Information About a Device Recipe
      tags:
      - Device
      parameters:
      - *id006
      - *id007
      - name: tagsAsObject
        in: query
        description: Return tags as an object map instead of an array
        required: false
        example: false
        schema:
          type: string
      - name: attributesAsObject
        in: query
        description: Return attributes as an object map instead of an array
        required: false
        example: false
        schema:
          type: string
      requestBody:
        description: Object containing new properties of the device recipe
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceRecipePatch'
      responses:
        '200':
          description: Updated device recipe information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceRecipe'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if device recipe was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    delete:
      summary: Deletes a Device Recipe
      tags:
      - Device
      parameters:
      - *id006
      - *id007
      responses:
        '200':
          description: If device recipe 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 device recipe was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    post:
      summary: Bulk Creates Devices Using This Recipe from a CSV
      tags:
      - Device
      parameters:
      - *id006
      - *id007
      requestBody:
        description: Object containing bulk creation info
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceRecipeBulkCreatePost'
      responses:
        '201':
          description: If devices were successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceRecipeBulkCreate'
        '202':
          description: If devices were enqueued to be created
          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 device recipe was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
  /applications/{applicationId}/device-recipes:
    get:
      summary: Returns the Device Recipes for an Application
      tags:
      - Device
      parameters:
      - &id008
        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 * recipe
        schema:
          type: string
      - name: tagsAsObject
        in: query
        description: Return tags as an object map instead of an array
        required: false
        example: false
        schema:
          type: string
      - name: attributesAsObject
        in: query
        description: Return attributes as an object map instead of an array
        required: false
        example: true
        schema:
          type: string
      responses:
        '200':
          description: Collection of device recipes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceRecipes'
        '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 Device Recipe for an Application
      tags:
      - Device
      parameters:
      - *id008
      - name: tagsAsObject
        in: query
        description: Return tags as an object map instead of an array
        required: false
        example: false
        schema:
          type: string
      - name: attributesAsObject
        in: query
        description: Return attributes as an object map instead of an array
        required: false
        example: true
        schema:
          type: string
      requestBody:
        description: New device recipe information
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceRecipePost'
      responses:
        '201':
          description: Successfully created device recipe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceRecipe'
        '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}/devices/{deviceId}:
    get:
      summary: Returns Payload Counts per Resolution in the Time Range Specified for This Device
      tags:
      - Device
      parameters:
      - &id009
        name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - &id010
        name: deviceId
        in: path
        description: ID associated with the device
        required: true
        example: 575ecf887ae143cd83dc4aa2
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: start
        in: query
        description: Start of range for payload count query (ms since epoch)
        required: false
        example: 0
        schema:
          type: string
          default: -2592000000
      - name: end
        in: query
        description: End of range for payload count query (ms since epoch)
        required: false
        example: 1465790400000
        schema:
          type: string
          default: 0
      - name: resolution
        in: query
        description: Resolution in milliseconds
        required: false
        example: 86400000
        schema:
          type: string
          enum:
          - '86400000'
          - '3600000'
          default: 86400000
      responses:
        '200':
          description: Sum of payload counts by date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payloadCountsBreakdown'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if device was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    patch:
      summary: Updates Information About a Device
      tags:
      - Device
      parameters:
      - *id009
      - *id010
      - name: tagsAsObject
        in: query
        description: Return tags as an object map instead of an array
        required: false
        example: true
        schema:
          type: string
      - name: attributesAsObject
        in: query
        description: Return attributes as an object map instead of an array
        required: false
        example: false
        schema:
          type: string
      requestBody:
        description: Object containing new properties of the device
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/devicePatch'
      responses:
        '200':
          description: Updated device information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if device was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    delete:
      summary: Removes All Device Data for the Specified Time Range. Defaults to All Data.
      tags:
      - Device
      parameters:
      - *id009
      - *id010
      - name: start
        in: query
        description: Start time of export (ms since epoch - 0 means now, negative is relative to now)
        required: false
        example: 1465790400000
        schema:
          type: string
          default: 1
      - name: end
        in: query
        description: End time of export (ms since epoch - 0 means now, negative is relative to now)
        required: false
        example: 1465790400000
        schema:
          type: string
          default: 0
      responses:
        '202':
          description: If data removal was successfully started
          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 device was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
    post:
      summary: Set the Current Connection Status of the Device
      tags:
      - Device
      parameters:
      - *id009
      - *id010
      requestBody:
        description: The current connection status of the device
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceConnectionStatus'
      responses:
        '200':
          description: If connection status was successfully applied
          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 device was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - BearerAuth: []
  /applications/{applicationId}/devices:
    get:
      summary: Retrieve the Composite Last Complete State of the Matching Devices
      tags:
      - Device
      parameters:
      - &id011
        name: applicationId
        in: path
        description: ID associated with the application
        required: true
        example: 575ec8687ae143cd83dc4a97
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
      - name: start
        in: query
        description: Start of time range to look at to build composite state
        required: false
        example: 1465790400000
        schema:
          type: string
          default: 1
      - name: end
        in: query
        description: End of time range to look at to build composite state
        required: false
        example: 1465790400000
        schema:
          type: string
          default: 0
      - name: attributes
        in: query
        description: Comma-separated list of attributes to include. When not provided, returns all attributes.
        required: false
        example: myAttr1,myAttr2
        schema:
          type: string
      - name: sortField
        in: query
        description: Field to sort the results by
        required: false
        example: name
        schema:
          type: string
          enum:
          - name
          - id
          - creationDate
          - lastUpdated
          - connectionStatus
          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: query
        in: query
        description: Device advanced query JSON object
        required: false
        schema:
          type: object
      responses:
        '200':
          description: Collection of composite last state of the devices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/compositeDevicesState'
        '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: Creates an Export of Payload Count Information for the Matching Devices
      tags:
      - Device
      parameters:
      - *id011
      requestBody:
        description: Object containing export configuration
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/devicesExportPayloadCountPost'
      responses:
        '202':
          description: If generation of export was successfully started
          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: []
    patch:
      summary: Update the Fields of One or More Devices
      tags:
      - Device
      parameters:
      - *id011
      requestBody:
        description: Object containing device query or IDs and update operations
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/devicesPatch'
      responses:
        '200':
          description: Object including an update log link and the number of devices updated, failed, and skipped
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/devicesUpdated'
        '202':
          description: Successfully queued bulk update job
          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:
  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>`.
  schemas:
    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
    attributeNamesResponse:
      title: Attribute Names Response
      description: Schema for a list of attribute names
      type: object
      properties:
        attributeNames:
          type: array
          items:
            $ref: '#/components/schemas/common/key'
          maxItems: 1000
    bulkDeleteResponse:
      title: Bulk Deletion Response
      description: Schema for the response to a bulk deletion
      type: object
      properties:
        removed:
          type: number
        failed:
          type: number
    bulkRestoreResponse:
      title: Bulk Restoration Response
      description: Schema for the response to a bulk restore request
      type: object
      properties:
        restored:
          type: number
        failed:
          type: number
    compositeDeviceState:
      title: Composite Device State
      description: Schema for a composite Device state
      type: object
      patternProperties:
        ^[0-9a-zA-Z_-]{1,255}$:
          type: object
          properties:
            value:
              type:
              - number
              - string
              - boolean
            time:
              $ref: '#/components/schemas/common/timeFormats'
      additionalProperties: false
    compositeDevicesState:
      title: Devices Composite State
      description: Schema for a collection of Composite Device State
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/common/objectId'
              name:
                $ref: '#/components/schemas/common/name'
              compositeState:
                $ref: '#/components/schemas/compositeDeviceState'
        count:
          type: integer
        totalCount:
          type: integer
        perPage:
          type: integer
        page:
          type: integer
        sortField:
          type: string
        sortDirection:
          $ref: '#/components/schemas/common/sortDirection'
        applicationId:
          $ref: '#/components/schemas/common/objectId'
        query:
          type: object
    device:
      title: Device
      description: Schema for a single Device
      type: object
      properties

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/losant/refs/heads/main/openapi/losant-device-api-openapi.yml