{"openapi":"3.1.0","info":{"title":"Things HTTP Bindings API","description":"This specification describes the HTTP Bindings API of the KPN Things Platform.","contact":{"name":"KPN Things Support","url":"https://portal.kpnthings.com/support","email":"iot-developer@kpn.com"},"version":"0.6.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"paths":{"/http/bindings":{"get":{"summary":"Retrieve HTTP bindings, filtered by query parameters.","description":"Retrieve all HTTP bindings that match the query parameters given.","operationId":"searchHttpBindings","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"clientId","in":"query","description":"Include only HTTP 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 HTTP 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":"type","in":"query","description":"Include only HTTP bindings of the specified type. Currently supported values are http-streamline  and http-senml.","style":"form","explode":true,"schema":{"type":"string","example":null},"example":"http-senml"},{"name":"createdBefore","in":"query","description":"Include only HTTP 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 HTTP 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 HTTP 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 HTTP 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 HTTP bindings. Only bindings that are accessible to the caller are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfHttpBindings","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.read"]}]},"post":{"summary":"Create a new HTTP binding.","description":"Create a new HTTP binding.","operationId":"createHttpBinding","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpBinding","example":null}}},"required":true},"responses":{"201":{"description":"The newly created HTTP binding'.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpBinding","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.create"]}]}},"/http/bindings/{bindingId}":{"get":{"summary":"Retrieve a HTTP binding by ID.","operationId":"getHttpBinding","parameters":[{"name":"bindingId","in":"path","description":"HTTP binding identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"responses":{"200":{"description":"The HTTP binding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpBinding","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.read"]}]},"put":{"summary":"Update a HTTP binding.","operationId":"setHttpBinding","parameters":[{"name":"bindingId","in":"path","description":"HTTP binding identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpBinding"}}},"required":true},"responses":{"200":{"description":"The updated HTTP binding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpBinding","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["connector-binding.update"]}]},"delete":{"summary":"Delete a HTTP binding.","operationId":"deleteHttpBinding","parameters":[{"name":"bindingId","in":"path","description":"HTTP Binding identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"responses":{"204":{"description":"HTTP binding has been deleted successfully."}},"security":[{"BearerAuth":["connector-binding.delete"]}]}}},"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},"HttpStreamlineBinding":{"type":"object","description":"A binding of a device to the HTTP connector using the streamline HTTP endpoint and message format.","properties":{"id":{"type":"string","format":"uuid","description":"The id of the binding.","example":"60e75fd6-44d2-474a-9557-39fbe246321e","readOnly":true},"type":{"type":"string","description":"The type of binding; must be 'http-streamline' for HttpStreamlineBinding.","example":"http-streamline"},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The id of the device that is bound to the HTTP 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}},"required":["deviceId","type"],"title":"HttpStreamlineBinding","example":null},"HttpSenmlBinding":{"type":"object","description":"A binding of a device to the HTTP connector using the SenML HTTP endpoint and message format.","properties":{"id":{"type":"string","format":"uuid","description":"The id of the binding.","example":"224ecc46-291d-482b-993f-c8b508adb0da","readOnly":true},"type":{"type":"string","description":"The type of binding; must be 'http-senml' for HttpSenmlBinding.","example":"http-senml"},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The id of the device that is bound to the HTTP 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},"sharedSecret":{"type":"string","description":"The shared secret that the device will use to generate a Things-Message-Token signatures for SenML uplinks.","example":"4dd797de-357f-4ad2-8caa-4c45f74eaad8","writeOnly":true}},"required":["deviceId","type"],"title":"HttpSenmlBinding","example":null},"HttpBinding":{"type":"object","description":"A binding of a device to the HTTP connector, which configures that the device can connect to the Things Platform using HTTP","discriminator":{"propertyName":"type","mapping":{"http-streamline":"#/components/schemas/HttpStreamlineBinding","http-senml":"#/components/schemas/HttpSenmlBinding"}},"oneOf":[{"$ref":"#/components/schemas/HttpStreamlineBinding","example":null},{"$ref":"#/components/schemas/HttpSenmlBinding","example":null}],"properties":{"id":{"type":"string","format":"uuid","description":"The id of the binding.","example":"224ecc46-291d-482b-993f-c8b508adb0da","readOnly":true},"type":{"type":"string","description":"The type of HTTP binding. Known values are: http-streamline and http-senml","example":"http-senml"},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The id of the device that is bound to the HTTP 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}},"required":["deviceId","type"],"title":"HttpBinding","example":null},"PageOfHttpBindings":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page","example":null},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/HttpBinding"},"example":null}},"example":null}],"description":"A paginated list of HTTP bindings","title":"PageOfHttpBindings","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}},"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"}}}}