Kolide Device Groups API

openapi: 3.0.0
info:
  version: '2023-05-26'
  title: K2 Admin Users Device Groups API
servers:
- url: https://api.kolide.com/
security:
- api_key: []
tags:
- name: Device Groups
paths:
  /device_groups/{deviceGroupId}/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
      - name: deviceGroupId
        in: path
        required: true
        description: The device group ID of the device
        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:
      - Device Groups
  /device_groups/{deviceGroupId}/memberships:
    post:
      summary: Add a Device to the Device Group
      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: deviceGroupId
        in: path
        required: true
        description: The device group ID of the device group member
        schema:
          type: string
      responses:
        '200':
          description: The newly created Device group member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device_group_member'
        '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_group_member_request_body'
      tags:
      - Device Groups
  /device_groups/{deviceGroupId}/memberships/{id}:
    delete:
      summary: Remove a specified Device from the Device Group
      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: deviceGroupId
        in: path
        required: true
        description: The device group ID of the device group member
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: The ID of the device group member
        schema:
          type: string
      responses:
        '200':
          description: The deleted Device group member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device_group_member'
        '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:
      - Device Groups
  /device_groups:
    get:
      summary: Fetch a list of Device groups
      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`created_at` , `name` , `description`\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:
          'created_at:':
            summary: search the 'created_at' property of the Device Group records using ':' operator
            value: created_at:2000-01-08T20:38:21Z
          created_at<:
            summary: search the 'created_at' property of the Device Group records using '<' operator
            value: created_at<2000-01-08T20:38:21Z
          created_at>:
            summary: search the 'created_at' property of the Device Group records using '>' operator
            value: created_at>2000-01-08T20:38:21Z
          'name:':
            summary: search the 'name' property of the Device Group records using ':' operator
            value: name:string
          name~:
            summary: search the 'name' property of the Device Group records using '~' operator
            value: name~string
          'description:':
            summary: search the 'description' property of the Device Group records using ':' operator
            value: description:string
          description~:
            summary: search the 'description' property of the Device Group records using '~' operator
            value: description~string
        schema:
          type: string
      responses:
        '200':
          description: A paginated collection of Device groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: 'Device Groups allow you to group devices together in ways that are

                      beneficial to your organization, both in the UI and programmatically

                      via the API.

                      '
                    type: array
                    items:
                      $ref: '#/components/schemas/device_group'
                  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/device_groups?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:
      - Device Groups
  /device_groups/{id}:
    get:
      summary: Fetch information for a specific Device group
      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 group
        schema:
          type: string
      responses:
        '200':
          description: 'Device Groups allow you to group devices together in ways that are

            beneficial to your organization, both in the UI and programmatically

            via the API.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device_group'
        '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:
      - Device Groups
components:
  schemas:
    person_group:
      type: object
      properties:
        id:
          type: string
          description: The canonical identifier for this group
        name:
          type: string
          description: The human-readable name for this group
    device_group_member_request_body:
      type: object
      properties:
        device_ids:
          description: Array of identifiers for the devices to be added to/removed from the group
          type: array
          items:
            type: string
    device_group_member:
      type: object
      properties:
        device_id:
          type: string
          description: Identifier of the device belonging to a group
        group_id:
          type: string
          description: Identifier of the group that the device belongs to
    device_group:
      type: object
      properties:
        id:
          type: string
          description: The canonical identifier for this group
        created_at:
          type: string
          description: A timestamp describing when the device group was created
          format: date-time
        name:
          type: string
          description: The human-readable name for this group
        description:
          type: string
          description: Longer-form details about this device group
        members_count:
          type: integer
          description: The number of member devices in this group
    device_authentication_mode:
      type: object
      properties:
        device_id:
          type: string
          description: The canonical identifier for the device
        authentication_mode:
          type: string
          description: 'Authentication mode describing who can authentication with this device.  Must be one of: only_registered_owner, only_registered_owner_or_group_members, anyone'
        person_groups:
          description: Description of the groups allowed to authenticate with this device
          type: array
          items:
            $ref: '#/components/schemas/person_group'
    device:
      type: object
      properties:
        id:
          type: string
          description: The canonical identifier for this device
        name:
          type: string
          description: The canonical human name for the device. May be edited via the web interface.
        registered_at:
          type: string
          description: The timestamp representing when the device was registered to its current owner
          format: date-time
        last_authenticated_at:
          type: string
          description: The timestamp representing when the device last authenticated with Kolide
          format: date-time
        last_seen_at:
          type: string
          description: The timestamp when the device was last seen by the Kolide agent
          format: date-time
        registered_owner_info:
          allOf:
          - description: Information for fetching the complete data on the registered owner of the device
          - $ref: '#/components/schemas/link-object'
        operating_system:
          type: string
          description: The operating system installed on the device
        hardware_model:
          type: string
          description: The specific hardware model of the device
        serial:
          type: string
          description: The hardware serial of the device. May not be applicable
        hardware_uuid:
          type: string
          description: The hardware UUID/UDID for the device. May not be applicable for some devices
        note:
          type: string
          description: Notes provided by a Kolide administrator (in markdown format)
        auth_state:
          type: string
          enum:
          - Will Block
          - Blocked
          - Notified
          - Good
          description: 'The authorization status of the device, one of: ''Good'', ''Notified'', ''Will Block'' or ''Blocked'''
        will_block_at:
          type: string
          description: If the auth status is 'Will Block', this timestamp describes when the device will be blocked by a failing check
          format: date-time
        product_image_url:
          type: string
          description: The URL of the device's product image
        auth_configuration:
          allOf:
          - description: Object describing the authentication configuration for the device. Will be null if the device is not registered.
          - $ref: '#/components/schemas/device_authentication_mode'
        device_type:
          type: string
          enum:
          - Mac
          - Linux
          - Windows
          - iOS
          - Android
          description: The platform type of the device
        form_factor:
          type: string
          enum:
          - Computer
          - Tablet
          - Phone
          description: The form factor of the device
    link-object:
      type: object
      properties:
        identifier:
          type: string
          description: the canonical identifier for this object
        link:
          type: string
          format: url
          description: the API URL where complete information about this object can be found
  securitySchemes:
    api_key:
      type: http
      scheme: bearer