{"openapi":"3.1.0","info":{"title":"Things LoRa Bindings API","description":"This specification describes the LoRa Bindings API of the KPN Things Platform.","contact":{"name":"KPN Things Support","url":"https://portal.kpnthings.com/support","email":"iot-developer@kpn.com"},"version":"1.0.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"paths":{"/lora/bindings":{"get":{"summary":"Retrieve LoRa bindings, filtered by query parameters.","description":"Retrieve all LoRa bindings that match the query parameters given.","operationId":"searchLoraBindings","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"clientId","in":"query","description":"Include only LoRa bindings for devices that are owned by the provided clientId.  If clientId is omitted, bindings from all devices owned by the calling client are included.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","example":null},"example":"79658ca8-f1ba-4c25-b824-93813e9fba76"},{"name":"deviceId","in":"query","description":"Include only LoRa bindings for the device identified by the provided deviceId.","style":"form","explode":true,"schema":{"$ref":"#/components/schemas/DeviceId","example":null},"example":"89b053c5-7380-4fc3-8fe6-8792e746580f"},{"name":"createdBefore","in":"query","description":"Include only LoRa bindings created before the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time","example":null},"example":"2025-05-01T00:00:00Z"},{"name":"createdSince","in":"query","description":"Include only LoRa bindings created at or after the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time","example":null},"example":"2025-05-01T00:00:00Z"},{"name":"modifiedBefore","in":"query","description":"Include only LoRa bindings modified before the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time","example":null},"example":"2025-04-01T00:00:00Z"},{"name":"modifiedSince","in":"query","description":"Include only LoRa bindings modified at or after the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time","example":null},"example":"2025-04-01T00:00:00Z"}],"responses":{"200":{"description":"Page of filtered LoRa bindings. Only bindings that are accessible to the caller are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfLoraBindings","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.read"]}]},"post":{"summary":"Create a new LoRa binding.","description":"Create a new LoRa binding.","operationId":"createLoraBinding","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoraBinding","example":null}}},"required":true},"responses":{"201":{"description":"The newly created LoRa binding'.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoraBinding","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.create"]}]}},"/lora/bindings/{bindingId}":{"get":{"summary":"Retrieve a LoRa binding by ID.","operationId":"getLoraBinding","parameters":[{"name":"bindingId","in":"path","description":"LoRa binding identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}},{"name":"refresh","in":"query","description":"When true, synchronizes the latest state from Actility ThingPark to the binding","style":"form","explode":true,"schema":{"type":"boolean","example":null}}],"responses":{"200":{"description":"The LoRa binding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoraBinding","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.read"]}]},"put":{"summary":"Update a LoRa binding.","operationId":"setLoraBinding","parameters":[{"name":"bindingId","in":"path","description":"LoRa binding identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoraBinding"}}},"required":true},"responses":{"200":{"description":"The updated LoRa binding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoraBinding","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.update"]}]},"delete":{"summary":"Delete a LoRa binding.","operationId":"deleteLoraBinding","parameters":[{"name":"bindingId","in":"path","description":"LoRa Binding identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"responses":{"204":{"description":"LoRa binding has been deleted successfully."}},"security":[{"BearerAuth":["connector-binding.delete"]}]}},"/lora/connectivity-plans":{"get":{"summary":"Retrieve LoRa connectivity plans that are available to the caller.","operationId":"listConnectivityPlans","responses":{"200":{"description":"List of connectivity plans available to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListOfLoraConnectivityPlans","example":null}}}}},"security":[{}]}},"/lora/device-profiles":{"get":{"summary":"Retrieve LoRa device profiles that are available to the caller.","operationId":"listDeviceProfiles","responses":{"200":{"description":"List of device profiles available to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListOfLoraDeviceProfiles","example":null}}}}},"security":[{}]}}},"components":{"schemas":{"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","example":"478a82d4-128f-47a6-aa61-2eac3f2a23ad","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","example":"imei:350266800610993","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","example":"deveui:ea8fa35e2cf3489f","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","example":"dvnuuid:ed8b73ac-f48f-4457-8ccc-9926cf28979f","pattern":"(?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$","title":"DvnUuidDeviceId"},"DeviceUrn-imei":{"type":"string","description":"IMEI-based device URN","example":"urn:dev:imei:350266800610993","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","example":"urn:dev:deveui:ea8fa35e2cf3489f","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","example":"urn:dev:dvnuuid:ed8b73ac-f48f-4457-8ccc-9926cf28979f","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid","example":null},{"$ref":"#/components/schemas/DeviceId-imei","example":null},{"$ref":"#/components/schemas/DeviceId-deveui","example":null},{"$ref":"#/components/schemas/DeviceId-dvnuuid","example":null},{"$ref":"#/components/schemas/DeviceUrn-imei","example":null},{"$ref":"#/components/schemas/DeviceUrn-deveui","example":null},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid","example":null}],"title":"DeviceId","example":null},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{},"example":null},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page.","example":null},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page.","example":null}},"required":["items"],"title":"Page","example":null},"LoraConnectivityPlan":{"type":"object","description":"Plan that contains the specifications of the LoRa connectivity for a device.","properties":{"id":{"type":"string","default":"kpn-cs/kpn-things-channel-mask-tdoa","description":"The id of the LoRa connectivity plan.","example":"kpn-cs/kpn-things-channel-mask-tdoa"},"name":{"type":"string","description":"Human readable name of the LoRa connectivity plan.","example":"KPN LoRa - Class A - Geolocation","readOnly":true}},"required":["id"],"title":"LoraConnectivityPlan","example":null},"LoraDeviceProfile":{"type":"object","description":"Profile that contains the specifications of the device class and the movement speed of a LoRa device.","properties":{"id":{"type":"string","default":"Slow moving V 1.0 Class A","description":"Identifier of the LoRa device profile.","example":"Slow moving V 1.0 Class A"},"name":{"type":"string","description":"Human readable name of the LoRa device profile.","example":"Slow moving V 1.0 Class A","readOnly":true}},"required":["id"],"title":"LoraDeviceProfile","example":null},"LoraBindingStatus":{"type":"string","description":"The status of a LoRa binding. Known values include: INVENTORY and ACTIVE","example":"ACTIVE","title":"LoraBindingStatus"},"LoraBinding":{"type":"object","description":"A binding of a device to the LoRa connector.","properties":{"id":{"type":"string","format":"uuid","description":"The id of the binding.","example":"224ecc46-291d-482b-993f-c8b508adb0da","readOnly":true},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The id of the device that is bound to the LoRa connector by the binding.","example":"11fb8757-c3a7-4a53-96e8-8d6b5a2f3b05"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the binding is created in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"createdBy":{"type":"string","description":"The user who created the binding.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the binding is last modified in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the binding.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"appEui":{"type":"string","description":"A globally unique identifier of the target application server. Must be a hex value with size 16 (8 bytes)","example":"51b5a651b5a32b51","pattern":"^[0-9a-fA-F]{16}$"},"appKey":{"type":"string","description":"The encryption key used for messages during every over the air activation.","example":"abe284ec8f8a063a0790d782b7b4f7cc","pattern":"^[0-9a-fA-F]{32}$","writeOnly":true},"connectivityPlan":{"$ref":"#/components/schemas/LoraConnectivityPlan","example":null},"deviceProfile":{"$ref":"#/components/schemas/LoraDeviceProfile","example":null},"status":{"$ref":"#/components/schemas/LoraBindingStatus","example":null}},"required":["appEui","connectivityPlan","deviceId","deviceProfile","status"],"title":"LoraBinding","example":null},"PageOfLoraBindings":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page","example":null},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LoraBinding"},"example":null}},"example":null}],"description":"A paginated list of LoRa bindings","title":"PageOfLoraBindings","example":null},"Problem":{"type":"object","description":"Error information details","properties":{"type":{"type":"string","format":"uri-reference","default":"about:blank","description":"A URI reference that uniquely identifies the problem type only in the\ncontext of the provided API. Opposed to the specification in RFC-9457,\nit is neither recommended to be dereferenceable and point to a\nhuman-readable documentation nor globally unique for the problem type.","example":"/some/uri-reference"},"title":{"type":"string","description":"A short summary of the problem type. Written in English and readable\nfor engineers, usually not suited for non technical stakeholders and\nnot localized.","example":"some title for the error situation"},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","example":400,"exclusiveMaximum":600,"minimum":100},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem that is helpful to locate the problem and give advice on how\nto proceed. Written in English and readable for engineers, usually not\nsuited for non technical stakeholders and not localized.","example":"Some description for the error situation"},"instance":{"type":"string","format":"uri-reference","description":"A URI reference that identifies the specific occurrence of the problem,\ne.g. by adding a fragment identifier or sub-path to the problem type.\nMay be used to locate the root of this problem in the source code.","example":"/some/uri-reference#specific-occurrence-context"}},"title":"Problem","example":null},"ListOfLoraConnectivityPlans":{"type":"object","description":"A list of LoRa connectivity plans","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LoraConnectivityPlan"},"example":null}},"required":["items"],"title":"ListOfLoraConnectivityPlans","example":null},"ListOfLoraDeviceProfiles":{"type":"object","description":"A list of LoRa device profiles","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LoraDeviceProfile"},"example":null}},"required":["items"],"title":"ListOfLoraDeviceProfiles","example":null}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":{"cursor":{"name":"cursor","in":"query","description":"String that encodes all necessary information to retrieve a page.","style":"form","explode":true,"schema":{"type":"string","format":"cursor"}},"limit":{"name":"limit","in":"query","description":"Limit the number of results (per page).","style":"form","explode":true,"schema":{"type":"integer","default":50}},"sort":{"name":"sort","in":"query","description":"Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.","style":"form","explode":true,"schema":{"type":"string"},"example":"createdAt,-name"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}}}