Kolide Devices API

openapi: 3.0.0
info:
  version: '2023-05-26'
  title: K2 Admin Users Devices API
servers:
- url: https://api.kolide.com/
security:
- api_key: []
tags:
- name: Devices
paths:
  /devices/{deviceId}/open_issues:
    get:
      summary: Fetch a list of Issues
      parameters:
      - name: x-kolide-api-version
        in: header
        description: Specify the API version to be used
        required: false
        schema:
          type: string
          default: '2023-05-26'
      - name: cursor
        in: query
        description: Specify the cursor to begin returning results from
        required: false
        schema:
          type: string
          default: ''
      - name: per_page
        in: query
        description: Specify the number of records to return in each response.
        required: false
        schema:
          type: integer
          format: int32
          maximum: 100
          minimum: 1
          default: 25
      - name: query
        in: query
        description: "A query clause used to filter the set of resources returned. Use\n`:` for exact matches (including for boolean fields), `~` for\npartial-string matches. `:[\"a\",\"b\",\"c\"]` or `:[1,2,3]`\ncan be used for fields that support multi-value search.\n Datetime fields support exact-matching\n(`:`) as well as less-than (`<`) and greater-than (`>`). The\nsearchable fields are:\n\n`id` , `detected_at` , `resolved_at` , `blocks_device_at` , `title` , `issue_key` , `issue_value` , `exempted` , `check_id` , `device_id` , `last_rechecked_at`\n\nSearch clauses can be combined with the ` AND ` and ` OR ` operators.\n\nFor more information, see the [search documentation](https://www.kolide.com/docs/developers/api#search).\n"
        required: false
        examples:
          'id:':
            summary: search the 'id' property of the Issue records
            value: id:["a", "b", "c"]
          'detected_at:':
            summary: search the 'detected_at' property of the Issue records using ':' operator
            value: detected_at:2000-01-08T20:38:21Z
          detected_at<:
            summary: search the 'detected_at' property of the Issue records using '<' operator
            value: detected_at<2000-01-08T20:38:21Z
          detected_at>:
            summary: search the 'detected_at' property of the Issue records using '>' operator
            value: detected_at>2000-01-08T20:38:21Z
          'resolved_at:':
            summary: search the 'resolved_at' property of the Issue records using ':' operator
            value: resolved_at:2000-01-08T20:38:21Z
          resolved_at<:
            summary: search the 'resolved_at' property of the Issue records using '<' operator
            value: resolved_at<2000-01-08T20:38:21Z
          resolved_at>:
            summary: search the 'resolved_at' property of the Issue records using '>' operator
            value: resolved_at>2000-01-08T20:38:21Z
          'blocks_device_at:':
            summary: search the 'blocks_device_at' property of the Issue records using ':' operator
            value: blocks_device_at:2000-01-08T20:38:21Z
          blocks_device_at<:
            summary: search the 'blocks_device_at' property of the Issue records using '<' operator
            value: blocks_device_at<2000-01-08T20:38:21Z
          blocks_device_at>:
            summary: search the 'blocks_device_at' property of the Issue records using '>' operator
            value: blocks_device_at>2000-01-08T20:38:21Z
          'title:':
            summary: search the 'title' property of the Issue records using ':' operator
            value: title:string
          title~:
            summary: search the 'title' property of the Issue records using '~' operator
            value: title~string
          'issue_key:':
            summary: search the 'issue_key' property of the Issue records using ':' operator
            value: issue_key:string
          issue_key~:
            summary: search the 'issue_key' property of the Issue records using '~' operator
            value: issue_key~string
          'issue_value:':
            summary: search the 'issue_value' property of the Issue records using ':' operator
            value: issue_value:string
          issue_value~:
            summary: search the 'issue_value' property of the Issue records using '~' operator
            value: issue_value~string
          'exempted:':
            summary: search the 'exempted' property of the Issue records using ':' operator
            value: exempted:true
          'check_id:':
            summary: search the 'check_id' property of the Issue records using ':' operator
            value: check_id:string
          check_id~:
            summary: search the 'check_id' property of the Issue records using '~' operator
            value: check_id~string
          'device_id:':
            summary: search the 'device_id' property of the Issue records using ':' operator
            value: device_id:string
          device_id~:
            summary: search the 'device_id' property of the Issue records using '~' operator
            value: device_id~string
          'last_rechecked_at:':
            summary: search the 'last_rechecked_at' property of the Issue records using ':' operator
            value: last_rechecked_at:2000-01-08T20:38:21Z
          last_rechecked_at<:
            summary: search the 'last_rechecked_at' property of the Issue records using '<' operator
            value: last_rechecked_at<2000-01-08T20:38:21Z
          last_rechecked_at>:
            summary: search the 'last_rechecked_at' property of the Issue records using '>' operator
            value: last_rechecked_at>2000-01-08T20:38:21Z
        schema:
          type: string
      - name: deviceId
        in: path
        required: true
        description: The device ID of the issue
        schema:
          type: string
      responses:
        '200':
          description: A paginated collection of Issues
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: 'An Issue is created when a device fails a check. Some checks, when

                      they fail, will produce multiple Issues, each with a unique

                      primary_key_value.

                      '
                    type: array
                    items:
                      $ref: '#/components/schemas/issue'
                  pagination:
                    type: object
                    description: Information about the current and next pages of results
                    properties:
                      next:
                        type: string
                        format: uri
                        description: The full URL that should be used to fetch the next page of results. This will be blank if there are no more results to fetch
                        example: https://api.kolide.com/open_issues?per_page=10&cursor=Imyw
                      current_cursor:
                        type: string
                        description: the pagination cursor used to fetch this page of results
                        example: Miwy
                      next_cursor:
                        type: string
                        description: 'the pagination cursor that can be used to fetch the page of results following the current page. This will be blank if there are no more results to fetch '
                        example: NCw0
                      count:
                        type: integer
                        description: the number of records in the current page of results
                        example: 10
        '401':
          description: An 'unauthorized' response may occur for features restricted by or unavailable to your organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: an error message describing why the endpoint is unavailable
                    example: This feature has been disabled by your organization
        '403':
          description: A 'forbidden' response may occur if the API key does not have necessary permissions to perform certain actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: a succinct error message
                    example: Forbidden
                  message:
                    type: string
                    description: A longer-form error message explaining the reason for the response
                    example: The API key used is not authorized to perform this action
      tags:
      - Devices
  /devices/{deviceId}/authentication_mode:
    patch:
      summary: Update an existing Device authentication mode
      parameters:
      - name: x-kolide-api-version
        in: header
        description: Specify the API version to be used
        required: false
        schema:
          type: string
          default: '2023-05-26'
      - name: deviceId
        in: path
        required: true
        description: The device ID of the device authentication mode
        schema:
          type: string
      responses:
        '200':
          description: The updated Device authentication mode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device_authentication_mode'
        '401':
          description: An 'unauthorized' response may occur for features restricted by or unavailable to your organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: an error message describing why the endpoint is unavailable
                    example: This feature has been disabled by your organization
        '403':
          description: A 'forbidden' response may occur if the API key does not have necessary permissions to perform certain actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: a succinct error message
                    example: Forbidden
                  message:
                    type: string
                    description: A longer-form error message explaining the reason for the response
                    example: The API key used is not authorized to perform this action
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/device_authentication_mode_request_body'
      tags:
      - Devices
    put:
      summary: Update an existing Device authentication mode
      parameters:
      - name: x-kolide-api-version
        in: header
        description: Specify the API version to be used
        required: false
        schema:
          type: string
          default: '2023-05-26'
      - name: deviceId
        in: path
        required: true
        description: The device ID of the device authentication mode
        schema:
          type: string
      responses:
        '200':
          description: The updated Device authentication mode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device_authentication_mode'
        '401':
          description: An 'unauthorized' response may occur for features restricted by or unavailable to your organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: an error message describing why the endpoint is unavailable
                    example: This feature has been disabled by your organization
        '403':
          description: A 'forbidden' response may occur if the API key does not have necessary permissions to perform certain actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: a succinct error message
                    example: Forbidden
                  message:
                    type: string
                    description: A longer-form error message explaining the reason for the response
                    example: The API key used is not authorized to perform this action
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/device_authentication_mode_request_body'
      tags:
      - Devices
  /devices/{deviceId}/registration:
    delete:
      summary: Delete a device registration
      description: 'Remove an existing device registration. This will prevent the

        registered owner from authenticating with the device. If this device

        is the only registered device for the person, their

        Trust-On-First-Use (TOFU) status will be reset, allowing them to

        register another device without needing admin approval. Deleting a

        mobile device''s registration will also remove the device from the

        Kolide.

        '
      parameters:
      - name: x-kolide-api-version
        in: header
        description: Specify the API version to be used
        required: false
        schema:
          type: string
          default: '2023-05-26'
      - name: deviceId
        in: path
        required: true
        description: The device ID of the device registration
        schema:
          type: string
      responses:
        '200':
          description: The deleted Device registration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device_registration'
        '401':
          description: An 'unauthorized' response may occur for features restricted by or unavailable to your organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: an error message describing why the endpoint is unavailable
                    example: This feature has been disabled by your organization
        '403':
          description: A 'forbidden' response may occur if the API key does not have necessary permissions to perform certain actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: a succinct error message
                    example: Forbidden
                  message:
                    type: string
                    description: A longer-form error message explaining the reason for the response
                    example: The API key used is not authorized to perform this action
      tags:
      - Devices
  /devices/{deviceId}/check_refreshes:
    post:
      summary: Create a new Check refresh
      parameters:
      - name: x-kolide-api-version
        in: header
        description: Specify the API version to be used
        required: false
        schema:
          type: string
          default: '2023-05-26'
      - name: deviceId
        in: path
        required: true
        description: The device ID of the check refresh
        schema:
          type: string
      responses:
        '200':
          description: The newly created Check refresh
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/check_refresh'
        '401':
          description: An 'unauthorized' response may occur for features restricted by or unavailable to your organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: an error message describing why the endpoint is unavailable
                    example: This feature has been disabled by your organization
        '403':
          description: A 'forbidden' response may occur if the API key does not have necessary permissions to perform certain actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: a succinct error message
                    example: Forbidden
                  message:
                    type: string
                    description: A longer-form error message explaining the reason for the response
                    example: The API key used is not authorized to perform this action
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/check_refresh_request_body'
      tags:
      - Devices
  /devices/{deviceId}/check_results:
    get:
      summary: Fetch a list of Check results
      parameters:
      - name: x-kolide-api-version
        in: header
        description: Specify the API version to be used
        required: false
        schema:
          type: string
          default: '2023-05-26'
      - name: cursor
        in: query
        description: Specify the cursor to begin returning results from
        required: false
        schema:
          type: string
          default: ''
      - name: per_page
        in: query
        description: Specify the number of records to return in each response.
        required: false
        schema:
          type: integer
          format: int32
          maximum: 100
          minimum: 1
          default: 25
      - name: query
        in: query
        description: "A query clause used to filter the set of resources returned. Use\n`:` for exact matches (including for boolean fields), `~` for\npartial-string matches. `:[\"a\",\"b\",\"c\"]` or `:[1,2,3]`\ncan be used for fields that support multi-value search.\n Datetime fields support exact-matching\n(`:`) as well as less-than (`<`) and greater-than (`>`). The\nsearchable fields are:\n\n`device_display_name` , `ran_at` , `check_name` , `status`\n\nSearch clauses can be combined with the ` AND ` and ` OR ` operators.\n\nFor more information, see the [search documentation](https://www.kolide.com/docs/developers/api#search).\n"
        required: false
        examples:
          'device_display_name:':
            summary: search the 'device_display_name' property of the Check Results records using ':' operator
            value: device_display_name:string
          device_display_name~:
            summary: search the 'device_display_name' property of the Check Results records using '~' operator
            value: device_display_name~string
          'ran_at:':
            summary: search the 'ran_at' property of the Check Results records using ':' operator
            value: ran_at:2000-01-08T20:38:21Z
          ran_at<:
            summary: search the 'ran_at' property of the Check Results records using '<' operator
            value: ran_at<2000-01-08T20:38:21Z
          ran_at>:
            summary: search the 'ran_at' property of the Check Results records using '>' operator
            value: ran_at>2000-01-08T20:38:21Z
          'check_name:':
            summary: search the 'check_name' property of the Check Results records using ':' operator
            value: check_name:string
          check_name~:
            summary: search the 'check_name' property of the Check Results records using '~' operator
            value: check_name~string
          'status:':
            summary: search the 'status' property of the Check Results records using ':' operator
            value: status:enumerated-value
        schema:
          type: string
      - name: deviceId
        in: path
        required: true
        description: The device ID of the check
        schema:
          type: string
      responses:
        '200':
          description: A paginated collection of Check results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: 'A Check Result describes the data returned the last time a check ran on a single device.

                      '
                    type: array
                    items:
                      $ref: '#/components/schemas/check_result'
                  pagination:
                    type: object
                    description: Information about the current and next pages of results
                    properties:
                      next:
                        type: string
                        format: uri
                        description: The full URL that should be used to fetch the next page of results. This will be blank if there are no more results to fetch
                        example: https://api.kolide.com/check_results?per_page=10&cursor=Imyw
                      current_cursor:
                        type: string
                        description: the pagination cursor used to fetch this page of results
                        example: Miwy
                      next_cursor:
                        type: string
                        description: 'the pagination cursor that can be used to fetch the page of results following the current page. This will be blank if there are no more results to fetch '
                        example: NCw0
                      count:
                        type: integer
                        description: the number of records in the current page of results
                        example: 10
        '401':
          description: An 'unauthorized' response may occur for features restricted by or unavailable to your organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: an error message describing why the endpoint is unavailable
                    example: This feature has been disabled by your organization
        '403':
          description: A 'forbidden' response may occur if the API key does not have necessary permissions to perform certain actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: a succinct error message
                    example: Forbidden
                  message:
                    type: string
                    description: A longer-form error message explaining the reason for the response
                    example: The API key used is not authorized to perform this action
      tags:
      - Devices
  /devices:
    get:
      summary: Fetch a list of Devices
      parameters:
      - name: x-kolide-api-version
        in: header
        description: Specify the API version to be used
        required: false
        schema:
          type: string
          default: '2023-05-26'
      - name: cursor
        in: query
        description: Specify the cursor to begin returning results from
        required: false
        schema:
          type: string
          default: ''
      - name: per_page
        in: query
        description: Specify the number of records to return in each response.
        required: false
        schema:
          type: integer
          format: int32
          maximum: 100
          minimum: 1
          default: 25
      - name: query
        in: query
        description: "A query clause used to filter the set of resources returned. Use\n`:` for exact matches (including for boolean fields), `~` for\npartial-string matches. `:[\"a\",\"b\",\"c\"]` or `:[1,2,3]`\ncan be used for fields that support multi-value search.\n Datetime fields support exact-matching\n(`:`) as well as less-than (`<`) and greater-than (`>`). The\nsearchable fields are:\n\n`id` , `name` , `registered_at` , `last_authenticated_at` , `serial` , `note` , `hardware_uuid` , `device_type` , `will_block_at`\n\nSearch clauses can be combined with the ` AND ` and ` OR ` operators.\n\nFor more information, see the [search documentation](https://www.kolide.com/docs/developers/api#search).\n"
        required: false
        examples:
          'id:':
            summary: search the 'id' property of the Device records
            value: id:["a", "b", "c"]
          'name:':
            summary: search the 'name' property of the Device records using ':' operator
            value: name:string
          name~:
            summary: search the 'name' property of the Device records using '~' operator
            value: name~string
          'registered_at:':
            summary: search the 'registered_at' property of the Device records using ':' operator
            value: registered_at:2000-01-08T20:38:21Z
          registered_at<:
            summary: search the 'registered_at' property of the Device records using '<' operator
            value: registered_at<2000-01-08T20:38:21Z
          registered_at>:
            summary: search the 'registered_at' property of the Device records using '>' operator
            value: registered_at>2000-01-08T20:38:21Z
          'last_authenticated_at:':
            summary: search the 'last_authenticated_at' property of the Device records using ':' operator
            value: last_authenticated_at:2000-01-08T20:38:21Z
          last_authenticated_at<:
            summary: search the 'last_authenticated_at' property of the Device records using '<' operator
            value: last_authenticated_at<2000-01-08T20:38:21Z
          last_authenticated_at>:
            summary: search the 'last_authenticated_at' property of the Device records using '>' operator
            value: last_authenticated_at>2000-01-08T20:38:21Z
          'serial:':
            summary: search the 'serial' property of the Device records using ':' operator
            value: serial:string
          serial~:
            summary: search the 'serial' property of the Device records using '~' operator
            value: serial~string
          'note:':
            summary: search the 'note' property of the Device records using ':' operator
            value: note:string
          note~:
            summary: search the 'note' property of the Device records using '~' operator
            value: note~string
          'hardware_uuid:':
            summary: search the 'hardware_uuid' property of the Device records using ':' operator
            value: hardware_uuid:string
          hardware_uuid~:
            summary: search the 'hardware_uuid' property of the Device records using '~' operator
            value: hardware_uuid~string
          'device_type:':
            summary: search the 'device_type' property of the Device records using ':' operator
            value: device_type:enumerated-value
          'will_block_at:':
            summary: search the 'will_block_at' property of the Device records using ':' operator
            value: will_block_at:2000-01-08T20:38:21Z
          will_block_at<:
            summary: search the 'will_block_at' property of the Device records using '<' operator
            value: will_block_at<2000-01-08T20:38:21Z
          will_block_at>:
            summary: search the 'will_block_at' property of the Device records using '>' operator
            value: will_block_at>2000-01-08T20:38:21Z
        schema:
          type: string
      responses:
        '200':
          description: A paginated collection of Devices
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: A Device is a computer or mobile device enrolled into Kolide
                    type: array
                    items:
                      $ref: '#/components/schemas/device'
                  pagination:
                    type: object
                    description: Information about the current and next pages of results
                    properties:
                      next:
                        type: string
                        format: uri
                        description: The full URL that should be used to fetch the next page of results. This will be blank if there are no more results to fetch
                        example: https://api.kolide.com/devices?per_page=10&cursor=Imyw
                      current_cursor:
                        type: string
                        description: the pagination cursor used to fetch this page of results
                        example: Miwy
                      next_cursor:
                        type: string
                        description: 'the pagination cursor that can be used to fetch the page of results following the current page. This will be blank if there are no more results to fetch '
                        example: NCw0
                      count:
                        type: integer
                        description: the number of records in the current page of results
                        example: 10
        '401':
          description: An 'unauthorized' response may occur for features restricted by or unavailable to your organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: an error message describing why the endpoint is unavailable
                    example: This feature has been disabled by your organization
        '403':
          description: A 'forbidden' response may occur if the API key does not have necessary permissions to perform certain actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: a succinct error message
                    example: Forbidden
                  message:
                    type: string
                    description: A longer-form error message explaining the reason for the response
                    example: The API key used is not authorized to perform this action
      tags:
      - Devices
  /devices/{id}:
    get:
      summary: Fetch information for a specific Device
      parameters:
      - name: x-kolide-api-version
        in: header
        description: Specify the API version to be used
        required: false
        schema:
          type: string
          default: '2023-05-26'
      - name: id
        in: path
        required: true
        description: The ID of the device
        schema:
          type: string
      responses:
        '200':
          description: A Device is a computer or mobile device enrolled into Kolide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device'
        '401':
          description: An 'unauthorized' response may occur for features restricted by or unavailable to your organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: an error message describing why the endpoint is unavailable
                    example: This feature has been disabled by your organization
        '403':
          description: A 'forbidden' response may occur if the API key does not have necessary permissions to perform certain actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
    

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