openapi: 3.2.0 info: title: Location & Occupancy Telemetry API version: '1.0' description: Real-time and historical Kio Cloud apps data including location tracking, occupancy, and telemetry. contact: name: Kontakt.io Support url: https://support.kontakt.io email: support@kontakt.io termsOfService: https://kontakt.io/terms-of-service summary: Real-time and historical Kio Cloud apps data including location tracking, occupancy, and telemetry. servers: - url: https://apps.cloud.us.kontakt.io description: 'Kio Cloud US ' - url: https://apps.cloud.uk.kontakt.io description: Kio Cloud UK security: - API Key - 1: [] tags: - name: Telemetry paths: /v3/telemetry: parameters: [] get: summary: Retrieve telemetry by Tracking ID responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Telemetry' examples: Portal Beam: value: content: - trackingId: fd:45:0a:68:25:7d timestamp: '2022-03-20T23:39:00Z' batteryLevel: 99 channel: 38 humidity: 18 lightIntensity: 0 rssi: -62 sourceId: 12Bh000T temperature: 19.226562 airQuality: 125 roomNumber: 220 numberOfPeopleDetected: 0 secondsSincePeopleDetection: 13 firmware: '2.6' model: 31 txPowerDbm: -4 uniqueId: 11rc007c calibratedRssi1m: -69 moving: false Smart Badge: value: content: - trackingId: ca:26:7b:8a:f1:0c timestamp: '2022-03-20T23:26:00Z' batteryLevel: 78 channel: 38 clickCounter: 0 movementCounter: 1 rssi: -64 sourceId: 14:16:9d:82:6d:80 temperature: 14.746094 secondButtonClickCounter: 0 roomNumber: 65535 firmware: '2.6' model: 30 txPowerDbm: -4 uniqueId: 10tH008F calibratedRssi1m: -69 moving: false Asset Tag 2: value: content: - trackingId: 00:fa:b6:01:ff:f8 timestamp: '2022-03-20T23:26:00Z' batteryLevel: 98 channel: 39 rssi: -88 sourceId: 10:b3:c6:ba:17:a0 roomNumber: 4 model: 33 txPowerDbm: -4 uniqueId: 11eZ01m6 calibratedRssi1m: -69 moving: false Anchor Beacon 2: value: content: - trackingId: eb:b9:85:66:73:dc timestamp: '2022-03-20T23:26:00Z' batteryLevel: 94 channel: 39 rssi: -65 sourceId: Mv1640 temperature: 14.78125 roomNumber: 0 firmware: '2.6' model: 34 txPowerDbm: -12 uniqueId: 11a5037J calibratedRssi1m: -77 moving: false '429': $ref: '#/components/responses/error-429' operationId: get-telemetry description: 'Returns telemetry data for a single trackingId (MAC address) or filter by multiple IDs. **IMPORTANT** - startTime and endTime is limited to a 24 hour duration - Set size to 2000 **NOTE:** Telemetry response data varies by product model and configured settings. Example responses provided for Portal Beam, Smart Badge, Asset Tag 2, and Anchor Beacon 2.' parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/size' - $ref: '#/components/parameters/sort' - schema: type: string example: '2022-03-21T04:25:44.927375Z' in: query name: endTime description: Filter by telemetry timestamp range end time required: true - schema: type: string example: '2022-03-20T23:25:44.927392Z' in: query name: startTime description: Filter by telemetry timestamp range start time required: true - schema: type: string example: fd:45:0a:68:25:7d in: query description: Filter by comma-separated list of tracking IDs (MAC address; alpha characters all lowercase). name: trackingId tags: - Telemetry security: - api_key: [] components: schemas: Telemetry: description: Telemetry data varies by product model and configured settings. type: object x-examples: example-1: links: - rel: self href: https://apps.cloud.us.kontakt.io/v3/telemetry?page=0&sort=trackingId&trackingId=gOnxcsiieN&endTime=2021-10-07T06:41:08.042043Z&startTime=2021-10-07T05:41:07.985Z&size=2 page: startTime: '2021-10-07T05:41:07.985Z' endTime: '2021-10-07T06:41:08.042043Z' hasNext: false size: 2 content: - trackingId: gOnxcsiieN timestamp: '2021-10-07T05:41:07.985Z' beaconTimestamp: '2021-10-07T11:41:07.988Z' gatewayTimestamp: '2021-10-07T11:41:07.988Z' cloudTimestamp: '2021-10-07T11:41:07.988Z' accelerometerSensitivity: 3 accelerometerX: -8 accelerometerY: 2 accelerometerZ: -6 batteryLevel: 5 channel: 3 clickCounter: 3 humidity: 8 lightIntensity: 8 movementCounter: 2 rssi: 4 sourceId: CKgIEuTDpY temperature: 42.012993 timeSinceDoubleClick: 394 timeSinceDoubleTap: 2877 timeSinceMovement: 2694 timeSinceTap: 2129 firmware: '1.0' model: 12 txPowerDbm: 4 uniqueId: LWdBIM calibratedRssi1m: -77 calibratedRssi0m: -36 eddystoneNamespace: a018cecb01ceaa095297 eddystoneInstanceId: 05ae686502ab eddystoneEphemeralId: 333e88d5007c35e9 iBeaconProximity: 23e16784-c2b5-43b6-b199-49de659535de iBeaconMajor: 57095 iBeaconMinor: 20686 moving: true examples: [] title: Telemetry Data Model properties: content: type: array uniqueItems: true minItems: 1 items: type: object properties: trackingId: type: string minLength: 1 description: Tracking Id. timestamp: type: string minLength: 1 description: Timestamp when telemetry was received by Kio Cloud. beaconTimestamp: type: string minLength: 1 description: Telemetry timestamp from beacon. gatewayTimestamp: type: string minLength: 1 description: Telemetry timestamp from gateway. cloudTimestamp: type: string minLength: 1 description: Timestamp when telemetry comes to Kontakt.io cloud. accelerometerSensitivity: type: number description: 'Accelerometer sensitivity. The accelerometer sensitivity represents the scale in which the following numbers are given. A sensitivity of 16 means that the numbers are in 16 mg units, or 0.016g. To decode a triple [0, 1, 64] with sensitivity 16.: X component is just 0 Y component is -1 * 16 mg = -0.016g Z component is 64 * 16mg = 1.024g So the raw vector [0, -1, 64] gets multiplied by 0.016g and the resulting vector is: [0, -0.016, 1.024] g.016g.' accelerometerX: type: number description: 'Accelerometer in X axis. ' accelerometerY: type: number description: Accelerometer in Y axis. accelerometerZ: type: number description: Accelerometer in Z axis. batteryLevel: type: number description: Device battery level in percentage (%). channel: type: number description: Channel. clickCounter: type: number description: Click counter for default button (BLUE button). secondButtonClickCounter: type: number description: Click counter for second button (RED button). humidity: type: number description: Humidity reading in percentage (%). lightIntensity: type: number description: Light intensity in percentage (%) rssi: type: number description: RSSI in dB movementCounter: type: number description: Movement counter. sourceId: type: string minLength: 1 description: Source Id. temperature: type: number description: Temperature reading in Celsius. airQuality: type: number description: Index 0 to 255. The higher the value, the worse the air pollution. roomNumber: type: number description: Room number detected by device sensor. numberOfPeopleDetected: type: number description: Detected number of people in the room (count). secondsSincePeopleDetection: type: number description: Time since last detection in seconds. timeSinceClick: type: number description: Time since click. timeSinceDoubleTap: type: number description: Time since double click. timeSinceMovement: type: number description: Time since movement. timeSinceTap: type: number description: Time since tap. firmware: type: string minLength: 1 description: Firmware version of scanned device. model: type: number description: Scanned device version number. txPowerDbm: type: number description: Transmission Power (in dBm) of a scanned device. uniqueId: type: string minLength: 1 description: Unique identifier (id) of a scanned device. calibratedRssi1m: type: number description: Calibrated RSSI value at 1 meter from a scanned device. calibratedRssi0m: type: number description: Calibrated RSSI value at 0 meters from a scanned device. moving: type: boolean description: Flag showing whether device is currently in motion. eddystoneNamespace: type: string minLength: 1 description: Namespace value from Eddystone UID frame. eddystoneInstanceId: type: string minLength: 1 description: Instance ID value from Eddystone UID frame. eddystoneEphemeralId: type: string minLength: 1 description: Ephemeral value from Eddystone EID frame. iBeaconProximity: type: string minLength: 1 description: Proximity UUID value from iBeacon frame. iBeaconMajor: type: number description: Major value from iBeacon frame. iBeaconMinor: type: number description: Minor value from iBeacon frame. required: - trackingId - timestamp - beaconTimestamp - gatewayTimestamp - cloudTimestamp parameters: size: name: size in: query schema: type: string default: '20' description: Size of the page to retrieve. sort: name: sort in: query schema: type: string default: asc example: ?sort=firstname&sort=lastname,asc enum: - asc - desc description: 'Sort objects returned in the response. Format property,property ' page: name: page in: query schema: type: integer default: '0' description: Page you want to retrieve; 0 indexed. responses: error-429: description: Rate limit exceeded. The response has no body. headers: Retry-After: description: 'Indicates how long to wait before making a new request. The response includes this header twice: once with an HTTP-date format (e.g., "Wed, 21 Oct 2015 07:28:00 GMT") and once with delay-seconds format (e.g., "120").' schema: type: string required: true content: text/plain: null securitySchemes: api_key: type: apiKey in: header description: 'Your Kio Cloud API Key is required to be provided in the `Api-Key` header in each API call. Get your API Key: sign in to **Kio Cloud** > select **Users** > select **Security** > copy your **Server API Key**.' name: Api-Key x-: null