Kontakt.io Command API

openapi: 3.2.0
info:
  title: Device Management Command API
  x-logo:
    url: https://kontakt.io/wp-content/themes/kontakt/dist/img/site-header/logo.svg
    backgroundColor: '#FFFFFF'
  version: '10'
  description: 'This Kontakt.io API provides direct access to all Kio Cloud Device Management resources. It allows integrating device administration functionality into 3rd-party applications without the need to build all underlying logic from the ground up.


    ## Authentication


    All requests must include a **JWT Bearer token** in the `Authorization` header, obtained via the [OAuth2 Client Credentials flow](https://developer.kontakt.io/docs/entity-management-integration-api/0255c5646ab01-authentication-o-auth2-client-credentials-flow).


    > **Deprecated:** The `Api-Key` header is still accepted for backward compatibility but is deprecated and will be removed. Do not use it for new integrations.


    Each API call requires the `Accept` header with the API version. **By default, set to the current stable version:** `application/vnd.com.kontakt+json;version=10`

    '
  contact:
    name: Support
    url: https://support.kontakt.io
    email: support@kontakt.io
  termsOfService: https://kontakt.io/legal-documents/terms-of-sale-and-service/
servers:
- url: https://dm-api.cloud.us.kontakt.io
  description: Kio Cloud US region
- url: https://dm-api.cloud.uk.kontakt.io
  description: Kio Cloud UK region
security:
- bearer_token: []
- api_key: []
tags:
- name: Command
  description: Commands are a special type of Configs used for initiating some management tasks, e.g. entering bootloader mode
paths:
  /command/encrypt:
    get:
      tags:
      - Command
      summary: Create Encrypted Commands
      description: Returns a list of Base64-encoded configs with encrypted commands for each of devices specified in a request
      parameters:
      - $ref: '#/components/parameters/UniqueIdList'
      - name: command
        in: query
        required: true
        description: 'A Command that should be encrypted in configs for each of devices specified in a request


          * `RESET` - Reboots the device

          * `NONCONNECTABLE` - Connectable BLE packets will be non-connectable until a next reboot

          * `SLEEP` - Device enters a sleep mode (stops broadcasting all packets)

          * `BLINK_10S` - Primary LED blinks for 10 seconds or LED blinks with the primary colour for 10 seconds

          * `BLINK_30S` - Primary LED blinks for 30 seconds or LED blinks with the primary colour for 30 seconds

          * `BLINK2_10S` - Secondary LED blinks for 10 seconds or LED blinks with the secondary colour for 10 seconds

          * `BLINK2_30S` - Secondary LED blinks for 30 seconds or LED blinks with the secondary colour for 30 seconds


          Please keep in mind that not all devices can support all of these commands. Refer to device specification to learn more.

          '
        schema:
          type: string
          enum:
          - RESET
          - NONCONNECTBLE
          - SLEEP
          - BLINK_10S
          - BLINK_30S
          - BLINK2_10S
          - BLINK2_30S
      - $ref: '#/components/parameters/accept'
      responses:
        '200':
          description: OK
          content:
            application/vnd.com.kontakt+json;version=10:
              schema:
                type: object
                properties:
                  commands:
                    type: array
                    items:
                      $ref: '#/components/schemas/EncryptedConfig'
                  searchMeta:
                    $ref: '#/components/schemas/SearchMeta'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - bearer_token: []
      - api_key: []
components:
  schemas:
    ApiError:
      type: object
      title: API Error
      properties:
        id:
          type: string
          description: Internal API error code
          example: API_ERROR_1693477316246
        status:
          type: number
          description: HTTP response status code
          example: 422
        cause:
          type: string
          description: General cause of the error
          example: ValidationError
        message:
          type: string
          description: Error message with an explanation of the problem
          example: Invalid value for field name
        details:
          type:
          - array
          - 'null'
          description: Optional details
          items:
            type: object
            properties:
              field:
                type: string
                example: name
              error:
                type: string
                description: Error name
                example: INVALID_VALUE
              message:
                type: string
                description: Error message
                example: Invalid value for field name
    EncryptedConfig:
      title: Encrypted Config/Command
      x-stoplight:
        id: yvjpgdrc5gygd
      type: object
      properties:
        uniqueId:
          type: string
          description: Unique ID of the device that can consume this Encrypted Config/Command.
        config:
          type: string
          format: byte
          description: Base64-encoded data with a new Config/Command for a Device with an Unique ID specified in the `uniqueId` field.
    SearchMeta:
      type: object
      title: Search Metadata
      description: Additional information, pagination and metadata about an API response
      externalDocs:
        description: Pagination model description
        url: /backend/management/pagination/
      properties:
        filter:
          type: string
          description: Filter query used in the API call
        startIndex:
          type: integer
          description: Start index for the results array
        maxResult:
          type: integer
          description: Maximum numbers of results in a single response
        prevResults:
          type: string
          description: URL for the previous page of results
          format: URL
        count:
          type:
          - integer
          - 'null'
          description: Number of results. Not `null` only when the `queryType` is set to `COUNTED` or `SEARCH_META`.
        orderBy:
          type: string
          enum:
          - CREATED
        nextResults:
          type: string
          format: URL
          description: URL for the next page of results
        queryType:
          description: Query type. `COUNTED` - returns a number of results in the `count` field. `SEARCH_META` - returns only the `searchMeta` object, but with a number of results in the `count` field.
          type: string
          enum:
          - NORMAL
          - COUNTED
          - SEARCH_META
          default: NORMAL
        order:
          type: string
          description: Sorting order - `ASC`ending (default) or `DESC`ending
          enum:
          - ASC
          - DESC
          default: ASC
  parameters:
    UniqueIdList:
      name: uniqueId
      in: query
      description: List of devices' unique ids
      required: true
      schema:
        type: array
        items:
          type: string
        example:
        - 11P10AvW
        - 11S13AhY
    accept:
      name: Accept
      in: header
      required: true
      schema:
        type: string
        default: application/vnd.com.kontakt+json;version=10
      description: Accept header is required.
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Provide a JWT in the `Authorization: Bearer <token>` header. This is the standard authentication method for all API requests.


        Obtain a token via the OAuth2 Client Credentials flow from the Kontakt.io Keycloak identity provider.'
    api_key:
      type: apiKey
      name: Api-Key
      in: header
      description: '**Deprecated — do not use for new integrations.** This method exists solely for backward compatibility and will be removed in a future release. Use JWT Bearer token authentication instead.


        If you still need an API Key: sign in to **Kio Cloud** > select **Users** > select **Security** > copy your **Server API Key**.'
    management_api_key:
      name: Api-Key
      type: apiKey
      in: header
      description: Special management API Key with additional privileges used by authorized users.
externalDocs:
  url: https://developer.kontakt.io