{ "openapi": "3.0.3", "info": { "title": "The Things Network Connector REST", "version": "v1", "description": "" }, "servers": [ { "url": "https://cloud.kaaiot.com/ttnc/api/v1", "description": "API Server" } ], "paths": { "/integrations": { "post": { "description": "Creates new application integration and returns it. \n
Application integration links a TTN application with a corresponding application in the KaaIoT platform.\n", "responses": { "201": { "description": "Application integration was successfully created.", "headers": { "Location": { "description": "URI in format `{schema}://{host}:{port}/api/v1/integrations/{id}`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppIntegrationResponse" }, "example": { "id": 267, "appName": "q4hhh0cckgmc6ivflvag", "ttnUsername": "lorawan-farm-app@ttn", "ttnIdentityServerHost": "eu1.cloud.thethings.network", "ttnJoinServerHost": "eu1.cloud.thethings.network", "ttnNetworkServerHost": "eu1.cloud.thethings.network", "ttnApplicationServerHost": "eu1.cloud.thethings.network", "ttnPlainMqttServerUrl": "eu1.cloud.thethings.network:1883", "ttnMqttIntegrationEnabled": true, "name": "Smart Farm", "description": "Smart farm LoRaWAN devices integration", "status": "ACTIVE" } } } } }, "security": [ { "oauth_2_0": [ "application:ttn-app-integration:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppIntegrationCreateRequest" }, "example": { "appName": "q4hhh0cckgmc6ivflvag", "ttnUsername": "lorawan-smart-farm@ttn", "ttnApiKeyId": "EJXRNLCPHQEIUTZLUSVLCAK26HINNSXS.AP4VEXNNY4DGRTOXHBAZ33HFDS67B5LVW.5CHH7RJPLR5WYDIGP7KAABI5EXAMPLE", "ttnIdentityServerHost": "eu1.cloud.thethings.network", "ttnJoinServerHost": "eu1.cloud.thethings.network", "ttnNetworkServerHost": "eu1.cloud.thethings.network", "ttnApplicationServerHost": "eu1.cloud.thethings.network", "ttnPlainMqttServerUrl": "eu1.cloud.thethings.network:1883", "ttnMqttIntegrationEnabled": true, "name": "Smart Farm", "description": "Smart farm LoRaWAN devices integration", "poolIds": [ "aXJuOnJjNzNkYmg3cTA6aWFtY29yZTo0YXRjaWNuaXNnOjpwb29sL2Rldg==" ] } } } } }, "get": { "description": "Returns application integrations. If 'status' parameter not used, then returns only ACTIVE application integrations.", "responses": { "200": { "description": "Application integrations are successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppIntegrationPageInfo" }, "example": { "totalElements": 2, "content": [ { "id": 267, "appName": "q4hhh0cckgmc6ivflvag", "ttnUsername": "lorawan-smart-farm@ttn", "ttnIdentityServerHost": "eu1.cloud.thethings.network", "ttnJoinServerHost": "eu1.cloud.thethings.network", "ttnNetworkServerHost": "eu1.cloud.thethings.network", "ttnApplicationServerHost": "eu1.cloud.thethings.network", "ttnPlainMqttServerUrl": "eu1.cloud.thethings.network:1883", "ttnMqttIntegrationEnabled": true, "name": "Smart Farm", "description": "Smart farm LoRaWAN devices integration", "status": "ACTIVE", "ttnConnectionState": "CONNECTED", "kpcConnectionState": "CONNECTED" }, { "id": 351, "appName": "0cckq4hhhgmc6ivflasd", "ttnUsername": "lorawan-smart-farm2@ttn", "ttnIdentityServerHost": "eu1.cloud.thethings.network", "ttnJoinServerHost": "eu1.cloud.thethings.network", "ttnNetworkServerHost": "eu1.cloud.thethings.network", "ttnApplicationServerHost": "eu1.cloud.thethings.network", "ttnMqttIntegrationEnabled": false, "name": "Smart Farm", "description": "Smart farm LoRaWAN devices integration", "status": "SUSPENDED", "ttnConnectionState": "DISCONNECTED", "ttnConnectionError": "Not authorized to connect", "kpcConnectionState": "CONNECTED" } ] } } } } }, "security": [ { "oauth_2_0": [ "ttn-app-integration:read" ] } ], "parameters": [ { "name": "appName", "in": "query", "description": "Filters application integrations by application name.", "required": false, "schema": { "type": "string" }, "example": "my-application" } ] } }, "/integrations/{appIntegrationId}": { "parameters": [ { "name": "appIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Application integration ID", "example": 351 } ], "get": { "description": "Returns application integration.", "responses": { "200": { "description": "Application integration is successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": 351, "appName": "0cckq4hhhgmc6ivflvag", "ttnUsername": "lorawan-smart-farm2@ttn", "ttnIdentityServerHost": "farmtenant.eu1.cloud.thethings.industries", "ttnNetworkServerHost": "farmtenant.eu1.cloud.thethings.industries", "ttnJoinServerHost": "farmtenant.eu1.cloud.thethings.industries", "ttnApplicationServerHost": "farmtenant.eu1.cloud.thethings.industries", "ttnPlainMqttServerUrl": "eu2.cloud.thethings.industries:1883", "name": "Smart Farm", "description": "Smart farm LoRaWAN devices integration", "status": "ACTIVE", "ttnMqttIntegrationEnabled": true, "ttnConnectionState": "DISCONNECTED", "ttnConnectionError": "Unable to connect to server", "kpcConnectionState": "CONNECTED" } } } } }, "security": [ { "oauth_2_0": [ "ttn-app-integration:read" ] } ] }, "patch": { "description": "Updates application integration.", "responses": { "200": { "description": "Application integration is successfully updated.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": 267, "appName": "q4hhh0cckgmc6ivflvag", "ttnUsername": "lorawan-farm-app@ttn", "ttnIdentityServerHost": "eu1.cloud.thethings.network", "ttnJoinServerHost": "eu1.cloud.thethings.network", "ttnNetworkServerHost": "eu1.cloud.thethings.network", "ttnApplicationServerHost": "eu1.cloud.thethings.network", "ttnPlainMqttServerUrl": "eu1.cloud.thethings.network:1883", "ttnMqttIntegrationEnabled": true, "name": "Smart Farm", "description": "Smart farm LoRaWAN devices integration", "status": "ACTIVE" } } } } }, "security": [ { "oauth_2_0": [ "ttn-app-integration:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppIntegrationUpdateRequest" }, "example": { "ttnNetworkServerHost": "farmtenant.eu1.cloud.thethings.industries", "ttnJoinServerHost": "farmtenant.eu1.cloud.thethings.industries", "ttnApplicationServerHost": "farmtenant.eu1.cloud.thethings.industries", "ttnApiKeyId": "EJXRNLCPHQEIUTZLUSVLCAK26HINNSXS.AP4VEXNNY4DGRTOXHBAZ33HFDS67B5LVW.5CHH7RJPLR5WYDIGP7KAABI5EXAMPLE", "name": "Smart Farm", "description": "Smart farm LoRaWAN devices integration" } } } } }, "delete": { "description": "Deletes application integration if there is no one device integration connected with this application integration.", "responses": { "204": { "description": "Application integration successfully deleted." } }, "security": [ { "oauth_2_0": [ "ttn-app-integration:delete" ] } ] } }, "/integrations/{appIntegrationId}/devices": { "parameters": [ { "name": "appIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Application integration ID", "example": 351 } ], "post": { "description": "Creates new device integrations. (Max - 5 device integrations per request). \n
Device integration connects an individual TTN LoRaWAN device to an endpoint (digital twin) in the KaaIoT platform.\n", "responses": { "201": { "description": "Device integrations are created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevIntegrationBatchResponse" }, "example": { "createdCount": 2, "failedCount": 1, "created": [ { "id": 10, "appVersionName": "0cckq4hhhgmc6ivflvag-v1", "ttnDeviceId": "eui-1b789bc1325a5", "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7476", "name": "Moisture monitor 25", "description": "Greenhouse 1", "status": "ACTIVE" }, { "id": 25, "appVersionName": "0cckq4hhhgmc6ivflvag-v2", "ttnDeviceId": "eui-1b789bc1325a6", "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7445", "name": "Moisture monitor 27", "description": "Greenhouse 1", "status": "ACTIVE" } ], "failed": [ { "ttnDeviceId": "eui-1b789bc1325b8", "reason": "Can't create endpoint for appIntegrationId [303], appVersionName [0cckq4hhhgmc6ivflvag-v1]" } ] } } } } }, "security": [ { "oauth_2_0": [ "ttn-app-integration:ttn-device-integration:create", "application:endpoint:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevIntegrationCreateRequest" }, "example": { "appVersionName": "q4hhh0cckgmc6ivflvag-v2", "devices": [ { "ttnDeviceId": "eui-1b789bc1325f8", "name": "Moisture monitor integration 25", "description": "Greenhouse 1", "endpointMetadata": { "name": "LoRa moisture sensor 25", "serial": "AC53743462-34" }, "endpointRelations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ] } ], "poolIds": [ "aXJuOnJjNzNkYmg3cTA6aWFtY29yZTo0YXRjaWNuaXNnOjpwb29sL2Rldg==" ] } } } } }, "get": { "description": "Returns all device integrations inside application integration.\nIf 'status' parameter not used, then returns only ACTIVE device integrations.\n", "responses": { "200": { "description": "Device integrations are successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevIntegrationPageInfo" }, "example": { "totalElements": 2, "content": [ { "id": 10, "appVersionName": "0cckq4hhhgmc6ivflvag-v1", "ttnDeviceId": "eui-1b789bc1325a5", "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7476", "name": "Moisture monitor integration 25", "description": "Greenhouse 1", "status": "ACTIVE" }, { "id": 25, "appVersionName": "0cckq4hhhgmc6ivflvag-v2", "ttnDeviceId": "eui-1b789bc1325a6", "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7445", "name": "Moisture monitor integration 28", "description": "Greenhouse 1", "status": "ACTIVE" } ] } } } } }, "security": [ { "oauth_2_0": [ "ttn-device-integration:read" ] } ] } }, "/integrations/{appIntegrationId}/devices/batch": { "parameters": [ { "name": "appIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Application integration ID", "example": 351 } ], "post": { "description": "Create a task to register a batch of device integrations within a specified application integration.", "responses": { "202": { "description": "Batch device integration registration task is accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDevIntegrationCreateAcceptedResponse" }, "example": { "taskId": "79c717d9-eedd-4f71-b9f8-86caf69809e4" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" } } } }, "403": { "description": "User does not have permissions to perform this operation." } }, "security": [ { "oauth_2_0": [ "ttn-app-integration:ttn-device-integration:create", "application:endpoint:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDevIntegrationCreateRequest" }, "example": { "appVersionName": "example_app_v1", "devices": [ { "ttnDeviceId": "eui-1b789bc1325a5", "joinEui": "800000000000000C", "devEui": "1B789BC1325A5", "appKey": "C8F86AFE569D72157616CCAB05E15D88", "frequencyPlanId": "EU_863_870_TTN", "lorawanVersion": "MAC_V1_0_3", "lorawanPhyVersion": "PHY_V1_0_3_REV_A", "supportsJoin": true, "multicast": false, "supportsClassB": false, "supportsClassC": false, "macSettings": { "rx2_data_rate_index": 0, "rx2_frequency": "869525000" }, "ttnDeviceName": "Moisture monitor 25", "ttnDeviceDescription": "Greenhouse 1", "name": "Moisture monitor integration 25", "description": "Greenhouse 1", "endpointMetadata": { "name": "LoRa moisture sensor 25", "serial": "AC53743462-34" }, "endpointRelations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ] } ], "poolIds": [ "aXJuOnJjNzNkYmg3cTA6aWFtY29yZTo0YXRjaWNuaXNnOjpwb29sL2Rldg==" ] } } } } } }, "/integrations/{appIntegrationId}/devices/batch/status": { "parameters": [ { "name": "appIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Application integration ID", "example": 351 } ], "get": { "description": "Returns batch device integration registration task status.", "responses": { "200": { "description": "Batch device integration registration task's status is successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDevIntegrationCreateStatusResponse" }, "example": { "createdCount": 2, "failedCount": 1, "created": [ { "id": 124, "devEui": "1B789BC1325A5", "ttnDeviceId": "eui-1b789bc1325a5", "appVersionName": "example_app_v1", "endpointId": "56726466-e454-23ac-340c-f34fefda7de4", "ttnDeviceName": "Moisture sensor 25", "ttnDeviceDescription": "Greenhouse 1", "name": "device-25", "endpointMetadata": { "name": "LoRa moisture sensor 25", "serial": "AC53743462-34" }, "endpointRelations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ] }, { "id": 125, "devEui": "1B789BC1325A8", "ttnDeviceId": "eui-1b789bc1325a8", "appVersionName": "example_app_v1", "endpointId": "56726466-e454-23ac-340c-f34fefda7df2", "ttnDeviceName": "Moisture sensor 28", "ttnDeviceDescription": "Greenhouse 1", "name": "device-28", "endpointMetadata": { "name": "LoRa moisture sensor 28", "serial": "AC53743462-37" } } ], "failed": [ { "devEui": "1B789BC1325A2", "reason": "Device integration for the specified device EUI already exists." } ] } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "oauth_2_0": [ "ttn-app-integration:read", "ttn-device-integration:read" ] } ], "parameters": [ { "name": "taskId", "in": "query", "description": "Batch device integration registration task ID.", "required": true, "schema": { "type": "string" }, "example": "79c717d9-eedd-4f71-b9f8-86caf69809e4" } ] } }, "/integrations/{appIntegrationId}/devices/{devIntegrationId}": { "parameters": [ { "name": "appIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Application integration ID", "example": 351 }, { "name": "devIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Device integration ID", "example": 568 } ], "get": { "description": "Returns device integration.", "responses": { "200": { "description": "Device integration is successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevIntegrationDetailedResponse" }, "example": { "id": 10, "appVersionName": "0cckq4hhhgmc6ivflvag-v1", "ttnDeviceId": "eui-1b789bc1325a5", "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7476", "name": "Moisture monitor integration 25", "description": "Greenhouse 1", "endpointMetadata": { "name": "LoRa moisture sensor 25", "serial": "AC53743462-34" }, "endpointRelations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ], "status": "ACTIVE" } } } } }, "security": [ { "oauth_2_0": [ "ttn-device-integration:read" ] } ] }, "patch": { "description": "Updates device integration.", "responses": { "200": { "description": "Device integration is successfully updated.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": 10, "appVersionName": "0cckq4hhhgmc6ivflvag-v1", "ttnDeviceId": "eui-1b789bc1325a5", "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7476", "name": "Moisture monitor integration 25", "description": "Greenhouse 1", "endpointMetadata": { "name": "LoRa moisture sensor 25", "serial": "AC53743462-34" }, "endpointRelations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ], "status": "ACTIVE" } } } } }, "security": [ { "oauth_2_0": [ "ttn-device-integration:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevIntegrationUpdateRequest" }, "example": { "name": "Moisture monitor integration 25", "description": "Greenhouse 1" } } } } } }, "/integrations/{appIntegrationId}/devices/{devIntegrationId}/status": { "parameters": [ { "name": "appIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Application integration ID", "example": 351 }, { "name": "devIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Device integration ID", "example": 568 } ], "put": { "description": "Sets the current device integration status.\nFor now, allowed status transitions are:\n\n", "responses": { "204": { "description": "Device integration status is successfully updated." } }, "security": [ { "oauth_2_0": [ "ttn-device-integration:update", "endpoint:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevIntegrationStatusUpdateRequest" }, "example": { "status": "SUSPENDED" } } } } } }, "/account-integrations": { "post": { "description": "Creates new account integration and returns it.\n
Account integration provides access to TTN gateways metadata and statistics (TTN account-level information).\n", "responses": { "201": { "description": "Account integration was successfully created.", "headers": { "Location": { "description": "URI in format `{schema}://{host}:{port}/api/v1/gateway-integrations/{id}`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountIntegrationResponse" }, "example": { "id": 25, "appName": "q4hhh0cckgmvagc6ivfl", "ttnUserId": "farm-industry", "ttnIdentityServerHost": "eu1.cloud.thethings.network", "name": "Smart Farm gateways", "description": "Smart farm LoRaWAN gateways integration", "status": "ACTIVE" } } } } }, "security": [ { "oauth_2_0": [ "application:ttn-account-integration:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountIntegrationCreateRequest" }, "example": { "appName": "q4hhh0cckgmvagc6ivfl", "ttnUserId": "farm-industry", "ttnApiKeyId": "EJXRNLCPHQEI6HINNSXSUTZLUSVLCAK2.AP4GRTOXHBAZ33HFDS67BVEXNNY4D5LVW.5CHH7KAABI57RJPLR5WYDIGPEXAMPLE", "ttnIdentityServerHost": "farmtenant.eu1.cloud.thethings.industries", "name": "Smart Farm gateways", "description": "Smart farm LoRaWAN gateways integration", "poolIds": [ "aXJuOnJjNzNkYmg3cTA6aWFtY29yZTo0YXRjaWNuaXNnOjpwb29sL2Rldg==" ] } } } } }, "get": { "description": "Returns account integrations. If 'status' parameter not used, then returns only ACTIVE account integrations.", "responses": { "200": { "description": "Account integrations are successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountIntegrationPageInfo" }, "example": { "totalElements": 1, "content": [ { "id": 25, "appName": "q4hhh0cckgmvagc6ivfl", "ttnUserId": "farm-industry", "ttnIdentityServerHost": "eu1.cloud.thethings.network", "name": "Smart Farm gateways", "description": "Smart farm LoRaWAN gateways integration", "status": "ACTIVE" } ] } } } } }, "security": [ { "oauth_2_0": [ "ttn-account-integration:read" ] } ], "parameters": [ { "name": "appName", "in": "query", "description": "Filters account integrations by KaaIoT application name.", "required": false, "schema": { "type": "string" }, "example": "my-application" } ] } }, "/account-integrations/{accountIntegrationId}": { "parameters": [ { "name": "accountIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account integration ID", "example": 25 } ], "get": { "description": "Returns account integration.", "responses": { "200": { "description": "Account integration is successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": 25, "appName": "q4hhh0cckgmvagc6ivfl", "ttnUserId": "farm-industry", "ttnIdentityServerHost": "eu1.cloud.thethings.network", "name": "Smart Farm gateways", "description": "Smart farm LoRaWAN gateways integration", "status": "ACTIVE" } } } } }, "security": [ { "oauth_2_0": [ "ttn-account-integration:read" ] } ] }, "patch": { "description": "Updates account integration.", "responses": { "200": { "description": "Account integration is successfully updated.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": 25, "appName": "q4hhh0cckgmvagc6ivfl", "ttnUserId": "farm-industry", "ttnIdentityServerHost": "eu1.cloud.thethings.network", "name": "Smart Farm gateways", "description": "Smart farm LoRaWAN gateways integration", "status": "ACTIVE" } } } } }, "security": [ { "oauth_2_0": [ "ttn-account-integration:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountIntegrationUpdateRequest" }, "example": { "ttnApiKeyId": "EJXRNLCPHQEIUTZLUSVLCAK26HINNSXS.AP4VEXNNY4DGRTOXHBAZ33HFDS67B5LVW.5CHH7RJPLR5WYDIGP7KAABI5EXAMPLE", "name": "Smart Farm", "description": "Smart farm LoRaWAN gateways integration" } } } } }, "delete": { "description": "Deletes account integration if there is no one gateway integration connected with this account integration.", "responses": { "204": { "description": "Account integration successfully deleted." } }, "security": [ { "oauth_2_0": [ "ttn-account-integration:delete" ] } ] } }, "/account-integrations/{accountIntegrationId}/gateways": { "parameters": [ { "name": "accountIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account integration ID", "example": 25 } ], "post": { "description": "Creates new gateway integrations. (Max - 5 gateway integrations per request).\n
Gateway integration maps a TTN LoRaWAN gateway to an endpoint on the KaaIoT platform.\n", "responses": { "201": { "description": "Gateway integrations are created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchGatewayIntegrationResponse" }, "example": { "createdCount": 1, "failedCount": 1, "created": [ { "id": 10, "appVersionName": "0cckq4hhhgmc6ivflvag-v1", "ttnGatewayId": "eui-1b789bc1325a5", "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7476", "name": "Farm 1 gateway", "description": "Greenhouse 1", "endpointMetadata": { "name": "LoRa farm gateway 1", "serial": "GA53627434" }, "endpointRelations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ], "ttnGatewayInfo": { "ttnGatewayEui": "70B04A33D57ED0F3", "ttnGatewayName": "Farm 1 gateway", "frequencyPlanId": "EU_863_870_TTN", "statusPublic": true, "locationPublic": false, "gatewayServerAddress": "farmtenant.eu1.cloud.thethings.industries", "enforceDutyCycle": false, "scheduleAnytimeDelay": 0.5 }, "status": "ACTIVE" } ], "failed": [ { "ttnGatewayId": "eui-1b789bc1325b8", "reason": "Can't create endpoint for gatewayIntegrationId [303], appVersionName [0cckq4hhhgmc6ivflvag-v1]" } ] } } } } }, "security": [ { "oauth_2_0": [ "ttn-account-integration:ttn-gateway-integration:create", "application:endpoint:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayIntegrationCreateRequest" }, "example": { "appVersionName": "q4hhh0cckgmc6ivflvag-v2", "gateways": [ { "ttnGatewayId": "dranginotest", "name": "Farm 1 gateway integration", "description": "Greenhouse 1", "endpointMetadata": { "name": "LoRa farm gateway 1", "serial": "GA53627434" }, "endpointRelations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ], "ttnGatewayInfo": { "ttnGatewayEui": "70B04A33D57ED0F3", "ttnGatewayName": "Farm 1 gateway", "frequencyPlanId": "EU_863_870_TTN", "statusPublic": true, "locationPublic": false, "gatewayServerAddress": "farmtenant.eu1.cloud.thethings.industries", "enforceDutyCycle": false, "scheduleAnytimeDelay": 0.5 } } ], "registerGatewaysOnTtn": true, "poolIds": [ "aXJuOnJjNzNkYmg3cTA6aWFtY29yZTo0YXRjaWNuaXNnOjpwb29sL2Rldg==" ] } } } } }, "get": { "description": "Returns all gateway integrations inside account integration.\nIf 'status' parameter not used, then returns only ACTIVE gateway integrations.\n", "responses": { "200": { "description": "Gateway integrations are successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayIntegrationPageInfo" }, "example": { "totalElements": 1, "content": [ { "id": 10, "appVersionName": "0cckq4hhhgmc6ivflvag-v1", "ttnGatewayId": "dranginotest", "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7476", "name": "Moisture monitor 1", "description": "", "endpointMetadata": { "name": "LoRa farm gateway 1", "serial": "GA53627434" }, "endpointRelations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ], "ttnGatewayInfo": { "ttnGatewayEui": "70B04A33D57ED0F3", "ttnGatewayName": "Farm 1 gateway", "frequencyPlanId": "EU_863_870_TTN", "statusPublic": true, "locationPublic": false, "gatewayServerAddress": "farmtenant.eu1.cloud.thethings.industries", "enforceDutyCycle": false, "scheduleAnytimeDelay": 0.5 }, "status": "ACTIVE" } ] } } } } }, "security": [ { "oauth_2_0": [ "ttn-gateway-integration:read" ] } ] } }, "/account-integrations/{accountIntegrationId}/gateways/{gatewayIntegrationId}": { "parameters": [ { "name": "accountIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account integration ID", "example": 25 }, { "name": "gatewayIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Gateway integration ID", "example": 142 } ], "patch": { "description": "Updates gateway integration.", "responses": { "200": { "description": "Gateway integration is successfully updated.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": 102, "appVersionName": "0cckq4hhhgmc6ivflvag-v1", "ttnGatewayId": "dranginotest", "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7476", "name": "Moisture monitor 1", "description": "", "endpointMetadata": { "name": "LoRa farm gateway 1", "serial": "GA53627434" }, "endpointRelations": [ { "type": "contains", "to": "f359de38-6763-11ed-9022-0242ac120002" }, { "type": "contains", "from": "518ab0c0-e505-4062-9f1f-408da7b3ea05" } ], "ttnGatewayInfo": { "ttnGatewayEui": "70B04A33D57ED0F3", "ttnGatewayName": "Farm 1 gateway", "frequencyPlanId": "EU_863_870_TTN", "statusPublic": true, "locationPublic": false, "gatewayServerAddress": "farmtenant.eu1.cloud.thethings.industries", "enforceDutyCycle": false, "scheduleAnytimeDelay": 0.5 }, "status": "ACTIVE" } } } } }, "security": [ { "oauth_2_0": [ "ttn-gateway-integration:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayIntegrationUpdateRequest" }, "example": { "name": "Farm 1 gateway", "description": "Greenhouse 1" } } } } } }, "/account-integrations/{accountIntegrationId}/gateways/{gatewayIntegrationId}/status": { "parameters": [ { "name": "accountIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account integration ID", "example": 25 }, { "name": "gatewayIntegrationId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Gateway integration ID", "example": 142 } ], "put": { "description": "Sets the current gateway integration status.\nFor now, allowed status transitions are:\n\n", "responses": { "204": { "description": "Gateway integration status is successfully updated." } }, "security": [ { "oauth_2_0": [ "ttn-gateway-integration:update", "endpoint:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayIntegrationStatusUpdateRequest" }, "example": { "status": "SUSPENDED" } } } } } }, "/ttn/applications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "TTN application ID", "example": "lorawan-smart-farm" } ], "post": { "description": "Returns TTN application with specified ID if it is accessible with current credentials.\n", "responses": { "200": { "description": "TTN application is successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtnApplicationResponse" }, "example": { "applicationId": "farm-app-id", "createdAt": "2021-12-20T14:07:10.599Z", "updatedAt": "2022-02-01T14:00:19.911Z", "name": "Farm application", "description": "Farm sensors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtnApplicationRequest" }, "example": { "username": "lorawan-smart-farm@ttn", "apiKeyId": "EJXRNLCPHQEIUTZLUSVLCAK26HINNSXS.AP4VEXNNY4DGRTOXHBAZ33HFDS67B5LVW.5CHH7RJPLR5WYDIGP7KAABI5EXAMPLE", "identityServerHost": "farmtenant.eu1.cloud.thethings.industries" } } } } } }, "/ttn/integrations/{id}/devices": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Application integration ID", "example": 351 } ], "get": { "description": "Returns all TTN devices available for the current application integration.", "responses": { "200": { "description": "TTN devices are successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": [ { "deviceId": "eui-70b3d57ed004a3f3", "applicationId": "ttn-app-id", "deviceEui": "70B3D57ED004A3F3", "joinEui": "D004A3F370B3D57E", "createdAt": "2021-12-20T14:07:10.599Z", "updatedAt": "2022-02-01T14:00:19.911Z", "name": "Room", "description": "Room temperature sensor", "attributes": { "alarm": "on" }, "location": { "latitude": 51.49426750477876, "longitude": 31.29522889852524, "altitude": 20.0, "source": "SOURCE_REGISTRY" } }, { "deviceId": "eui-70b3d57ed004a3f5", "applicationId": "ttn-app-id", "deviceEui": "70B3D57ED004A3F5", "joinEui": "D004A3F370B3D57E", "createdAt": "2021-12-20T14:07:10.599Z", "updatedAt": "2022-02-01T14:00:19.911Z", "name": "Kitchen" } ] } } } }, "security": [ { "oauth_2_0": [ "ttn-app-integration:read" ] } ] } }, "/ttn/integrations/{id}/devices/search": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Application integration ID", "example": 351 } ], "get": { "description": "Searches TTN devices available for the current application integration.\nIf all query parameters are omitted, all TTN devices are returned.\n", "responses": { "200": { "description": "TTN devices are successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": [ { "deviceId": "eui-70b3d57ed004a3f3", "applicationId": "ttn-app-id", "deviceEui": "70B3D57ED004A3F3", "joinEui": "D004A3F370B3D57E", "createdAt": "2021-12-20T14:07:10.599Z", "updatedAt": "2022-02-01T14:00:19.911Z", "name": "Room", "description": "Room temperature sensor", "attributes": { "alarm": "on" }, "location": { "latitude": 51.49426750477876, "longitude": 31.29522889852524, "altitude": 20.0, "source": "SOURCE_REGISTRY" } } ] } } } }, "security": [ { "oauth_2_0": [ "ttn-app-integration:read" ] } ], "parameters": [ { "name": "deviceId", "in": "query", "description": "Filters devices whose TTN device ID contains the specified substring.", "required": false, "schema": { "type": "string" }, "example": "eui-70b3" }, { "name": "name", "in": "query", "description": "Filters devices whose name contains the specified substring.", "required": false, "schema": { "type": "string" }, "example": "sensor" }, { "name": "deviceEui", "in": "query", "description": "Filters devices by Device EUI (16 hexadecimal characters).", "required": false, "schema": { "type": "string" }, "example": "70B3D57ED004A3F3" }, { "name": "joinEui", "in": "query", "description": "Filters devices by Join EUI (16 hexadecimal characters).", "required": false, "schema": { "type": "string" }, "example": "D004A3F370B3D57E" } ] } }, "/ttn/account-integrations/{id}/gateways": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Account integration ID", "example": 25 } ], "get": { "description": "Returns all TTN gateways available for the current gateway integration.", "responses": { "200": { "description": "TTN gateways are successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": [ { "gatewayId": "dranginotest", "gatewayEui": "A8FF241DCFF1AC40", "name": "gateway-dragino-1", "createdAt": "2022-04-27T15:14:37.254Z", "updatedAt": "2023-01-17T09:06:26.106581Z", "gatewayServerAddress": "eu1.cloud.thethings.network", "frequencyPlanId": "EU_863_870_TTN" }, { "gatewayId": "eui-70b3d57ed004a3f3", "gatewayEui": "70B3D57ED004A3F3", "name": "gateway-dragino-2", "createdAt": "2022-09-14T11:58:59.959263Z", "updatedAt": "2022-10-17T10:48:07.862799Z" } ] } } } }, "security": [ { "oauth_2_0": [ "ttn-account-integration:read" ] } ] } }, "/ttn/verification": { "post": { "description": "Verify input credentials.", "responses": { "200": { "description": "Credencials are successfully verified." } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtnVerificationRequest" }, "example": { "username": "lorawan-smart-farm@ttn", "apiKeyId": "EJXRNLCPHQEIUTZLUSVLCAK26HINNSXS.AP4VEXNNY4DGRTOXHBAZ33HFDS67B5LVW.5CHH7RJPLR5WYDIGP7KAABI5EXAMPLE", "plainMqttServerUrl": "eu1.cloud.thethings.network:1883" } } } } } } }, "components": { "securitySchemes": { "oauth_2_0": { "type": "oauth2", "description": "TTNC supports OAuth 2.0 for authenticating all API requests.\n", "flows": { "implicit": { "authorizationUrl": "https://auth.example.com/oauth/authorize", "scopes": {} } } } }, "schemas": { "AppIntegrationCreateRequest": { "type": "object", "properties": { "appName": { "type": "string", "description": "The KaaIoT platform application name." }, "ttnUsername": { "type": "string", "description": "The Things Network username (https://www.thethingsindustries.com/docs/integrations/mqtt/#note-on-using-the-tenant-id)." }, "ttnApiKeyId": { "type": "string", "description": "The Things Network application API key." }, "ttnIdentityServerHost": { "type": "string", "description": "The Things Network Identity Server host address.\n
The Identity Server manages user accounts, applications, devices, and gateways in TTN, and handles authentication (login, API keys, OAuth) and access control (permissions and rights).\n" }, "ttnNetworkServerHost": { "type": "string", "description": "The Things Network (TTN) Network Server host address.
If not configured that ttnIdentityServerHost will be used instead." }, "ttnJoinServerHost": { "type": "string", "description": "The Things Network Join Server host address.
If not configured that ttnIdentityServerHost will be used instead." }, "ttnApplicationServerHost": { "type": "string", "description": "The Things Network Application Server host address.
If not configured that ttnIdentityServerHost will be used instead." }, "ttnPlainMqttServerUrl": { "type": "string", "description": "The Things Network MQTT Server URL address.
Should be configured if MQTT integration is enabled." }, "ttnMqttIntegrationEnabled": { "type": "boolean", "description": "Enable TTN MQTT integration MQTT.
Sometimes it needs the data from TTN to come not via TTNC service, but for example via Node-red. In such a case, the device integration should not subscribe to MQTT messages from the TTN and we set this parameter to `false`.
The ttnPlainMqttServerUrl is not used when ttnMqttIntegrationEnabled is `false`." }, "name": { "type": "string", "description": "Application integration name." }, "description": { "type": "string", "description": "Application integration description." }, "poolIds": { "type": "array", "items": { "type": "string" }, "description": "An array of the unique identifiers of the pools to which the application integrations will be attached." } }, "required": [ "appName", "ttnUsername", "ttnApiKeyId", "ttnIdentityServerHost", "name" ] }, "AppIntegrationResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "Application integration unique identifier." }, "appName": { "type": "string", "description": "The KaaIoT platform application name." }, "ttnUsername": { "type": "string", "description": "The Things Network username." }, "ttnIdentityServerHost": { "type": "string", "description": "The Things Network Identity Server host address." }, "ttnNetworkServerHost": { "type": "string", "description": "The Things Network (TTN) Network Server host address." }, "ttnJoinServerHost": { "type": "string", "description": "The Things Network Join Server host address." }, "ttnApplicationServerHost": { "type": "string", "description": "The Things Network Application Server host address." }, "ttnPlainMqttServerUrl": { "type": "string", "description": "The Things Network MQTT Server URL address." }, "ttnMqttIntegrationEnabled": { "type": "boolean", "description": "Enable TTN MQTT integration MQTT. false when, for example, used Node-red for message parsing. In such a case ttnPlainMqttServerUrl not used." }, "name": { "type": "string", "description": "Application integration name." }, "description": { "type": "string", "description": "Application integration description." }, "status": { "type": "string", "description": "Application integration status.", "enum": [ "ACTIVE", "SUSPENDED" ] }, "poolIds": { "type": "array", "items": { "type": "string" }, "description": "An array of the unique identifiers of the pools to which the application integration will be attached." } }, "required": [ "id", "appName", "ttnUsername", "ttnIdentityServerHost", "ttnMqttIntegrationEnabled", "name", "status" ] }, "AppIntegrationDetailedResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "Application integration unique identifier." }, "appName": { "type": "string", "description": "The KaaIoT platform application name." }, "ttnUsername": { "type": "string", "description": "The Things Network username." }, "ttnIdentityServerHost": { "type": "string", "description": "The Things Network Identity Server host address." }, "ttnNetworkServerHost": { "type": "string", "description": "The Things Network (TTN) Network Server host address." }, "ttnJoinServerHost": { "type": "string", "description": "The Things Network Join Server host address." }, "ttnApplicationServerHost": { "type": "string", "description": "The Things Network Application Server host address." }, "ttnPlainMqttServerUrl": { "type": "string", "description": "The Things Network MQTT Server URL address." }, "ttnMqttIntegrationEnabled": { "type": "boolean", "description": "Enable TTN MQTT integration MQTT. false when, for example, used Node-red for message parsing. In such a case ttnPlainMqttServerUrl not used." }, "name": { "type": "string", "description": "Application integration name." }, "description": { "type": "string", "description": "Application integration description." }, "status": { "type": "string", "description": "Application integration status.", "enum": [ "ACTIVE", "SUSPENDED" ] }, "ttnConnectionState": { "type": "string", "description": "Application integration TTN MQTT connection state.\n
\n", "enum": [ "CONNECTED", "DISCONNECTED" ] }, "ttnConnectionError": { "type": "string", "description": "Error description (if there is any problem with the TTN MQTT connection)." }, "kpcConnectionState": { "type": "string", "description": "Tenant application integrations KPC MQTT connection state.\n
\n", "enum": [ "CONNECTED", "DISCONNECTED" ] }, "kpcConnectionError": { "type": "string", "description": "Error description (if there is any problem with the KPC MQTT connection for the tenant)." } }, "required": [ "id", "appName", "ttnUsername", "ttnIdentityServerHost", "ttnMqttIntegrationEnabled", "name", "status", "ttnConnectionState", "kpcConnectionState" ] }, "AppIntegrationPageInfo": { "type": "object", "properties": { "totalElements": { "type": "integer", "description": "Total number of elements available for retrieval. Current response may return only a part of all available elements." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/AppIntegrationDetailedResponse" } } } }, "AppIntegrationUpdateRequest": { "type": "object", "properties": { "ttnNetworkServerHost": { "type": "string", "description": "The Things Network (TTN) Network Server host address." }, "ttnJoinServerHost": { "type": "string", "description": "The Things Network Join Server host address." }, "ttnApplicationServerHost": { "type": "string", "description": "The Things Network Application Server host address." }, "ttnApiKeyId": { "type": "string", "description": "The Things Network application API key." }, "name": { "type": "string", "description": "Application integration name." }, "description": { "type": "string", "description": "Application integration description." } } }, "EndpointRelation": { "type": "object", "properties": { "type": { "type": "object", "description": "Relation type.", "enum": [ "contains" ] }, "from": { "type": "string", "description": "Endpoint ID having the outbound direction of relation type coming to the registering endpoint." }, "to": { "type": "string", "description": "Endpoint ID having the inbound direction of relation type coming from the registering endpoint." } }, "required": [ "type" ] }, "DevIntegrationItemCreate": { "type": "object", "properties": { "ttnDeviceId": { "type": "string", "description": "The Things Network device unique identifier." }, "name": { "type": "string", "description": "Device integration name." }, "description": { "type": "string", "description": "Device integration description." }, "endpointMetadata": { "type": "object", "description": "Allows the configuration of the metadata of endpoint that will be created during integration creation. \n
Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type.\n" }, "endpointRelations": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointRelation" }, "description": "Endpoint relation with other endpoints.\nOnly one of the directions - either `to` or `from`, must be specified in each relation entry.\nFor example, registering an endpoint that represents a room, you can specify two entries with the relation type `contains` - inbound from the endpoint representing a building (`from`), and outbound to the endpoint representing a sensor in that room (`to`).\n" } }, "required": [ "ttnDeviceId", "name" ] }, "DevIntegrationCreateRequest": { "type": "object", "properties": { "appVersionName": { "type": "string", "description": "The KaaIoT platform application version name that integrated devices should work in." }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DevIntegrationItemCreate" }, "description": "List of devices to create integration for." }, "poolIds": { "type": "array", "items": { "type": "string" }, "description": "An array of the unique identifiers of the pools to which the device integrations will be attached." } }, "required": [ "appVersionName", "devices" ] }, "DevIntegrationResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "Device integration unique identifier." }, "appVersionName": { "type": "string", "description": "The KaaIoT platform application version name." }, "ttnDeviceId": { "type": "string", "description": "The Things Network device unique identifier." }, "endpointId": { "type": "string", "description": "Kaa endpoint unique identifier." }, "name": { "type": "string", "description": "Device integration name." }, "description": { "type": "string", "description": "Device integration description." }, "status": { "type": "string", "description": "Device integration status.", "enum": [ "ACTIVE", "SUSPENDED" ] } }, "required": [ "id", "appVersionName", "ttnDeviceId", "endpointId", "name", "status" ] }, "DevIntegrationFailedResponse": { "type": "object", "properties": { "ttnDeviceId": { "type": "string", "description": "The Things Network device unique identifier." }, "reason": { "type": "string", "description": "Cause of failing device integration creation." } }, "required": [ "ttnDeviceId" ] }, "DevIntegrationBatchResponse": { "type": "object", "properties": { "createdCount": { "type": "integer", "description": "Count of device integrations with successful creation." }, "failedCount": { "type": "integer", "description": "Count of device integrations with failed creation." }, "created": { "type": "array", "items": { "$ref": "#/components/schemas/DevIntegrationResponse" }, "description": "Array of device integrations with successful creation." }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/DevIntegrationFailedResponse" }, "description": "Array of device integrations with failed creation." } }, "required": [ "createdCount", "failedCount", "created", "failed" ] }, "DevIntegrationPageInfo": { "type": "object", "properties": { "totalElements": { "type": "integer", "description": "Total number of elements available for retrieval. Current response may return only a part of all available elements." }, "content": { "type": "array", "items": { "type": "object" } } } }, "MacSettings": { "type": "object", "properties": { "rx2_data_rate_index": { "type": "number", "description": "Data rate index for Rx2. If unset, the default value from Network Server configuration or regional parameters specification will be used." }, "rx2_frequency": { "type": "string", "description": "Frequency for Rx2 (Hz). If unset, the default value from Network Server configuration or regional parameters specification will be used." } }, "required": [ "rx2_data_rate_index", "rx2_frequency" ] }, "BatchDevIntegrationItemCreate": { "type": "object", "properties": { "ttnDeviceId": { "type": "string", "description": "The Things Network device unique identifier. If not explicitly provided, the device identifier is automatically generated in the format:\n
`eui-` (e.g., `eui-70b3d57ed005eabc`).\n" }, "joinEui": { "type": "string", "description": "64-bit unique identifier (JoinEUI/AppEUI) in EUI-64 assigned to the LoRaWAN network’s Join Server by either its owner or operator." }, "devEui": { "type": "string", "description": "64-bit unique device identifier (DevEUI) in EUI-64 that uniquely identifies the end-device." }, "appKey": { "type": "string", "description": "128-bit Application Root Key (AppKey)." }, "frequencyPlanId": { "type": "string", "description": "The Things Network ID of the frequency plan used by this device. https://www.thethingsindustries.com/docs/reference/frequency-plans/" }, "lorawanVersion": { "type": "string", "description": "The Things Network LoRaWAN MAC version. Stored in Network Server. https://www.thethingsindustries.com/docs/api/reference/grpc/end_device/#enum:MACVersion" }, "lorawanPhyVersion": { "type": "string", "description": "The Things Network LoRaWAN PHY version. Stored in Network Server. https://www.thethingsindustries.com/docs/api/reference/grpc/end_device/#enum:PHYVersion" }, "supportsJoin": { "type": "boolean", "description": "The device supports join (OTAA)." }, "multicast": { "type": "boolean", "description": "Indicates whether this device represents a multicast group." }, "supportsClassB": { "type": "boolean", "description": "Whether the device supports class B." }, "supportsClassC": { "type": "boolean", "description": "Whether the device supports class C." }, "macSettings": { "$ref": "#/components/schemas/MacSettings" }, "ttnDeviceName": { "type": "string", "description": "TTN Device name." }, "ttnDeviceDescription": { "type": "string", "description": "TTN Device description." }, "name": { "type": "string", "description": "Device integration name." }, "description": { "type": "string", "description": "Device integration description." }, "endpointMetadata": { "type": "object", "description": "Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type." }, "endpointRelations": { "type": "array", "items": { "type": "object" }, "description": "Endpoint relation with other endpoints.\nOnly one of the directions - either `to` or `from`, must be specified in each relation entry.\nFor example, registering an endpoint that represents a room, you can specify two entries with the relation type `contains` - inbound from the endpoint representing a building (`from`), and outbound to the endpoint representing a sensor in that room (`to`).\n" } }, "required": [ "joinEui", "devEui", "appKey", "frequencyPlanId", "macSettings", "name" ] }, "BatchDevIntegrationCreateRequest": { "type": "object", "properties": { "appVersionName": { "type": "string", "description": "The KaaIoT platform application version name that integrated devices should work in." }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/BatchDevIntegrationItemCreate" } }, "poolIds": { "type": "array", "items": { "type": "string" }, "description": "An array of the unique identifiers of the pools to which the device integrations will be attached." } }, "required": [ "appVersionName" ] }, "BatchDevIntegrationCreateAcceptedResponse": { "type": "object", "properties": { "taskId": { "type": "string", "description": "Batch device integrations registration task ID." } }, "required": [ "taskId" ] }, "ClientErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error description." } }, "required": [ "message" ] }, "BatchDevIntegrationItemCreated": { "type": "object", "properties": { "id": { "type": "integer", "description": "Device integration unique identifier." }, "devEui": { "type": "string", "description": "64-bit unique device identifier in (EUI-64) that uniquely identifies the end-device (DevEUI)." }, "ttnDeviceId": { "type": "string", "description": "The Things Network device unique identifier." }, "appVersionName": { "type": "string", "description": "The KaaIoT platform application version name." }, "endpointId": { "type": "string", "description": "Endpoint ID." }, "ttnDeviceName": { "type": "string", "description": "TTN Device name." }, "ttnDeviceDescription": { "type": "string", "description": "TTN Device description." }, "name": { "type": "string", "description": "Device integration name." }, "description": { "type": "string", "description": "Device integration description." }, "endpointMetadata": { "type": "object", "description": "Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type." }, "endpointRelations": { "type": "array", "items": { "type": "object" }, "description": "Endpoint relation with other endpoints.\nOnly one of the directions - either `to` or `from`, must be specified in each relation entry.\nFor example, registering an endpoint that represents a room, you can specify two entries with the relation type `contains` - inbound from the endpoint representing a building (`from`), and outbound to the endpoint representing a sensor in that room (`to`).\n" } }, "required": [ "id", "devEui", "ttnDeviceId", "appVersionName", "endpointId", "name" ] }, "BatchDevIntegrationItemFailed": { "type": "object", "properties": { "devEui": { "type": "string", "description": "64-bit unique device identifier in (EUI-64) that uniquely identifies the end-device (DevEUI)." }, "reason": { "type": "string", "description": "Cause of failing device integration creation." } }, "required": [ "devEui" ] }, "BatchDevIntegrationCreateStatusResponse": { "type": "object", "properties": { "createdCount": { "type": "integer", "description": "Count of device integrations with successful registration." }, "failedCount": { "type": "integer", "description": "Count of device integrations with failed registration." }, "created": { "type": "array", "items": { "$ref": "#/components/schemas/BatchDevIntegrationItemCreated" }, "description": "Array of device integrations with successful registration." }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/BatchDevIntegrationItemFailed" }, "description": "Array of device integrations with failed registration." } }, "required": [ "createdCount", "failedCount", "created", "failed" ] }, "DevIntegrationDetailedResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "Device integration unique identifier." }, "appVersionName": { "type": "string", "description": "The KaaIoT platform application version name." }, "ttnDeviceId": { "type": "string", "description": "The Things Network device unique identifier." }, "endpointId": { "type": "string", "description": "Kaa endpoint unique identifier." }, "name": { "type": "string", "description": "Device integration name." }, "description": { "type": "string", "description": "Device integration description." }, "endpointMetadata": { "type": "object", "description": "Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type." }, "endpointRelations": { "type": "array", "items": { "type": "object" }, "description": "Endpoint relation with other endpoints.\nOnly one of the directions - either `to` or `from`, must be specified in each relation entry.\nFor example, registering an endpoint that represents a room, you can specify two entries with the relation type `contains` - inbound from the endpoint representing a building (`from`), and outbound to the endpoint representing a sensor in that room (`to`).\n" }, "status": { "type": "string", "description": "Device integration status.", "enum": [ "ACTIVE", "SUSPENDED" ] } }, "required": [ "id", "appVersionName", "ttnDeviceId", "endpointId", "name", "status" ] }, "DevIntegrationUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Device integration name." }, "description": { "type": "string", "description": "Device integration description." } } }, "DevIntegrationStatusUpdateRequest": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the device integration.\n

\n

\n

\n", "enum": [ "SUSPENDED" ] } }, "required": [ "status" ] }, "AccountIntegrationCreateRequest": { "type": "object", "properties": { "appName": { "type": "string", "description": "The KaaIoT platform application name." }, "ttnUserId": { "type": "string", "description": "The Things Network user ID. \n
It is the unique identifier (username) associated with your account.\n" }, "ttnApiKeyId": { "type": "string", "description": "The Things Network user level API key. \n
API key should be configured at least with such rights (minimum rights): \n
- view gateway information, \n
- view gateway status, \n
- create a gateway under user account, \n
- list the gateways the user is a collaborator of.\n" }, "ttnIdentityServerHost": { "type": "string", "description": "The Things Network Identity Server host address.\n
The Identity Server manages user accounts, applications, devices, and gateways in TTN, and handles authentication (login, API keys, OAuth) and access control (permissions and rights).\n" }, "name": { "type": "string", "description": "The KaaIoT platform account integration name.\n
The human readable name to help identify the account integration.\n" }, "description": { "type": "string", "description": "The KaaIoT platform account integration description." }, "poolIds": { "type": "array", "items": { "type": "string" }, "description": "An array of the unique identifiers of the pools to which the account integration will be attached." } }, "required": [ "appName", "ttnUserId", "ttnApiKeyId", "ttnIdentityServerHost", "name" ] }, "AccountIntegrationResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "Account integration unique identifier." }, "appName": { "type": "string", "description": "The KaaIoT platform application name." }, "ttnUserId": { "type": "string", "description": "The Things Network user ID." }, "ttnIdentityServerHost": { "type": "string", "description": "The Things Network Identity Server host address." }, "name": { "type": "string", "description": "Account integration name." }, "description": { "type": "string", "description": "Account integration description." }, "status": { "type": "string", "description": "Account integration status.", "enum": [ "ACTIVE", "SUSPENDED" ] }, "error": { "type": "string", "description": "Error description (if there is any problem with the TTN or KPC connection)." } }, "required": [ "id", "appName", "ttnUserId", "ttnIdentityServerHost", "name", "status" ] }, "AccountIntegrationPageInfo": { "type": "object", "properties": { "totalElements": { "type": "integer", "description": "Total number of elements available for retrieval. Current response may return only a part of all available elements." }, "content": { "type": "array", "items": { "type": "object" } } } }, "AccountIntegrationUpdateRequest": { "type": "object", "properties": { "ttnApiKeyId": { "type": "string", "description": "The Things Network user level API key. \n
API key should be configured at least with such rights (minimum rights): \n
- view gateway information, \n
- view gateway status, \n
- create a gateway under user account, \n
- list the gateways the user is a collaborator of.\n" }, "name": { "type": "string", "description": "The KaaIoT platform account integration name." }, "description": { "type": "string", "description": "The KaaIoT platform account integration description." } } }, "TtnGatewayInfo": { "type": "object", "properties": { "ttnGatewayEui": { "type": "string", "description": "The Things Network gateway EUI. A 64 bit extended unique identifier for your gateway. It should be provided to you by the manufacturer, or printed on the gateway package." }, "ttnGatewayName": { "type": "string", "description": "The Things Network gateway name. An optional human readable name to help identify your gateway." }, "frequencyPlanId": { "type": "string", "description": "The Things Network ID of the frequency plan used by this device. https://www.thethingsindustries.com/docs/reference/frequency-plans/" }, "statusPublic": { "type": "boolean", "description": "The status of this gateway may be publicly displayed." }, "locationPublic": { "type": "boolean", "description": "The location of this gateway may be publicly displayed." }, "gatewayServerAddress": { "type": "string", "description": "The address of the Gateway Server to connect to." }, "enforceDutyCycle": { "type": "boolean", "description": "Enforcing gateway duty cycle is recommended for all gateways to respect spectrum regulations. Disable enforcing the duty cycle only in controlled research and development environments." }, "scheduleAnytimeDelay": { "type": "number", "description": "Adjust the time that GS schedules class C messages in advance. This is useful for gateways that have a known high latency backhaul, like 3G and satellite." } }, "required": [ "ttnGatewayEui", "frequencyPlanId", "gatewayServerAddress" ] }, "GatewayIntegrationItemCreate": { "type": "object", "properties": { "ttnGatewayId": { "type": "string", "description": "The Things Network gateway unique identifier. \n
A mandatory identifier for you gateway that must be unique per network and cannot be changed after creation. Enter a value using lowercase letters, numbers and dashes. You can choose this freely.\n" }, "name": { "type": "string", "description": "The KaaIoT platform gateway integration name. \n
The human readable name to help identify your gateway integration.\n" }, "description": { "type": "string", "description": "The KaaIoT platform gateway integration description." }, "endpointMetadata": { "type": "object", "description": "Allows the configuration of the metadata of endpoint that will be created during integration creation. \nThe metadata of LoRaWAN device' \"digital twin\". Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type.\n" }, "endpointRelations": { "type": "array", "items": { "type": "object" }, "description": "Endpoint relation with other endpoints.\n
Only one of the directions - either `to` or `from`, must be specified in each relation entry.\n
For example, registering an endpoint that represents a room, you can specify two entries with the relation type `contains` - inbound from the endpoint representing a building (`from`), and outbound to the endpoint representing a sensor in that room (`to`).\n" }, "ttnGatewayInfo": { "$ref": "#/components/schemas/TtnGatewayInfo" } }, "required": [ "ttnGatewayId", "name" ] }, "GatewayIntegrationCreateRequest": { "type": "object", "properties": { "appVersionName": { "type": "string", "description": "The KaaIoT platform application version name with gateways' endpoints." }, "registerGatewaysOnTtn": { "type": "boolean", "description": "Used in case when we want to create not only gateway integration on KaaIoT platform but the gateway on the TTN.\n
If `true` then ttnGatewayInfo should be configured for the gateways.\n" }, "gateways": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayIntegrationItemCreate" }, "description": "List of TTN gateways to create integration for." }, "poolIds": { "type": "array", "items": { "type": "string" }, "description": "An array of the unique identifiers of the pools to which the gateway integrations will be attached." } }, "required": [ "appVersionName", "gateways" ] }, "GatewayIntegrationResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "The KaaIoT platform gateway integration unique identifier." }, "appVersionName": { "type": "string", "description": "The KaaIoT platform application version name." }, "ttnGatewayId": { "type": "string", "description": "The Things Network gateway unique identifier." }, "endpointId": { "type": "string", "description": "The KaaIoT endpoint unique identifier." }, "name": { "type": "string", "description": "The KaaIoT platform gateway integration name.\n
The human readable name to help identify the gateway integration.\n" }, "description": { "type": "string", "description": "The KaaIoT platform gateway integration description." }, "endpointMetadata": { "type": "object", "description": "Endpoint metadata consists of multiple key-value pairs (called fields) where keys are strings, and the values are of any JSON type.\n" }, "endpointRelations": { "type": "array", "items": { "type": "object" }, "description": "Endpoint relation with other endpoints.\nOnly one of the directions - either `to` or `from`, must be specified in each relation entry.\nFor example, registering an endpoint that represents a room, you can specify two entries with the relation type `contains` - inbound from the endpoint representing a building (`from`), and outbound to the endpoint representing a sensor in that room (`to`).\n" }, "ttnGatewayInfo": { "type": "object", "description": "Gateway information to register on The Things Network." }, "status": { "type": "string", "description": "Gateway integration status.", "enum": [ "ACTIVE", "SUSPENDED" ] } }, "required": [ "id", "appVersionName", "ttnGatewayId", "endpointId", "name", "status" ] }, "GatewayIntegrationFailedResponse": { "type": "object", "properties": { "ttnGatewayId": { "type": "string", "description": "The Things Network gateway unique identifier." }, "reason": { "type": "string", "description": "Cause of failing gateway integration creation." } }, "required": [ "ttnGatewayId" ] }, "BatchGatewayIntegrationResponse": { "type": "object", "properties": { "createdCount": { "type": "integer", "description": "Count of gateway integrations with successful creation." }, "failedCount": { "type": "integer", "description": "Count of gateway integrations with failed creation." }, "created": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayIntegrationResponse" }, "description": "Array of gateway integrations with successful creation." }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayIntegrationFailedResponse" }, "description": "Array of gateway integrations with failed creation." } }, "required": [ "createdCount", "failedCount", "created", "failed" ] }, "GatewayIntegrationPageInfo": { "type": "object", "properties": { "totalElements": { "type": "integer", "description": "Total number of elements available for retrieval. Current response may return only a part of all available elements." }, "content": { "type": "array", "items": { "type": "object" } } } }, "GatewayIntegrationUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "The KaaIoT platform gateway integration name." }, "description": { "type": "string", "description": "The KaaIoT platform gateway integration description." } } }, "GatewayIntegrationStatusUpdateRequest": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the gateway integration.\n

\n

\n

\n", "enum": [ "SUSPENDED" ] } }, "required": [ "status" ] }, "TtnApplicationRequest": { "type": "object", "properties": { "username": { "type": "string", "description": "The Things Network username (https://www.thethingsindustries.com/docs/integrations/mqtt/#note-on-using-the-tenant-id)." }, "apiKeyId": { "type": "string", "description": "The Things Network application API key." }, "identityServerHost": { "type": "string", "description": "The Things Network Identity Server host address." } }, "required": [ "username", "apiKeyId", "identityServerHost" ] }, "TtnApplicationResponse": { "type": "object", "properties": { "applicationId": { "type": "string", "description": "The Things Network application unique identifier." }, "createdAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the application was created." }, "updatedAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the application was updated." }, "name": { "type": "string", "description": "The Things Network application name." }, "description": { "type": "string", "description": "The Things Network application description." }, "attributes": { "type": "object", "description": "The Things Network application attributes. Application attributes consist of multiple key-value pairs ." } }, "required": [ "applicationId", "createdAt", "updatedAt", "name" ] }, "TtnVerificationRequest": { "type": "object", "properties": { "username": { "type": "string", "description": "The Things Network username." }, "apiKeyId": { "type": "string", "description": "The Things Network application API key." }, "plainMqttServerUrl": { "type": "string", "description": "The Things Network Plain MQTT Server URL." } }, "required": [ "username", "apiKeyId", "plainMqttServerUrl" ] }, "AppIntegrationExtResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "Application integration unique identifier." }, "appName": { "type": "string", "description": "The KaaIoT platform application name." }, "ttnUsername": { "type": "string", "description": "The Things Network username." }, "ttnIdentityServerHost": { "type": "string", "description": "The Things Network Identity Server host address." }, "ttnNetworkServerHost": { "type": "string", "description": "The Things Network (TTN) Network Server host address." }, "ttnJoinServerHost": { "type": "string", "description": "The Things Network Join Server host address." }, "ttnApplicationServerHost": { "type": "string", "description": "The Things Network Application Server host address." }, "ttnPlainMqttServerUrl": { "type": "string", "description": "The Things Network MQTT Server URL address." }, "ttnMqttIntegrationEnabled": { "type": "boolean", "description": "Is MQTT enabled in the TTN integration." }, "name": { "type": "string", "description": "Application integration name." }, "description": { "type": "string", "description": "Application integration description." }, "status": { "type": "string", "description": "Application integration status.", "enum": [ "ACTIVE", "SUSPENDED" ] }, "ttnConnectionState": { "type": "string", "description": "Application integration TTN MQTT connection state.\n
\n", "enum": [ "CONNECTED", "DISCONNECTED" ] }, "ttnConnectionError": { "type": "string", "description": "Error description (if there is any problem with the TTN MQTT connection)." }, "kpcConnectionState": { "type": "string", "description": "Tenant application integrations KPC MQTT connection state.\n
\n", "enum": [ "CONNECTED", "DISCONNECTED" ] }, "kpcConnectionError": { "type": "string", "description": "Error description (if there is any problem with the KPC MQTT connection for the tenant)." } }, "required": [ "id", "appName", "ttnUsername", "ttnIdentityServerHost", "ttnMqttIntegrationEnabled", "name", "status", "ttnConnectionState", "kpcConnectionState" ] }, "TtnDeviceLocation": { "type": "object", "properties": { "latitude": { "type": "number", "description": "The Things Network device latitude." }, "longitude": { "type": "number", "description": "The Things Network device longitude." }, "altitude": { "type": "number", "description": "The Things Network device altitude." }, "source": { "type": "string", "description": "The Things Network device source." } } }, "TtnDeviceResponse": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "The Things Network device unique identifier." }, "applicationId": { "type": "string", "description": "The Things Network application unique identifier." }, "deviceEui": { "type": "string", "description": "The Things Network device EUI." }, "joinEui": { "type": "string", "description": "The Things Network join EUI." }, "createdAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the device was created." }, "updatedAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the device was updated." }, "name": { "type": "string", "description": "The Things Network device name." }, "description": { "type": "string", "description": "The Things Network device description." }, "attributes": { "type": "object", "description": "The Things Network device attributes. Device attributes consist of multiple key-value pairs ." }, "location": { "$ref": "#/components/schemas/TtnDeviceLocation" } }, "required": [ "deviceId", "applicationId", "deviceEui", "joinEui", "createdAt", "updatedAt", "name" ] }, "TtnGatewaysResponse": { "type": "object", "properties": { "gatewayId": { "type": "string", "description": "The Things Network gateway unique identifier." }, "gatewayEui": { "type": "string", "description": "Gateway EUI (Extended Unique Identifier)." }, "name": { "type": "string", "description": "The Things Network gateway name." }, "description": { "type": "string", "description": "The Things Network gateway description." }, "createdAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the gateway was created." }, "updatedAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the gateway was updated." }, "deletedAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the gateway was deleted (if it is deleted)." }, "gatewayServerAddress": { "type": "string", "description": "The Things Network gateway server host." }, "frequencyPlanId": { "type": "string", "description": "The Things Network gateway frequency plan ID." } }, "required": [ "gatewayId", "gatewayEui", "name", "createdAt", "updatedAt" ] } } } }