# Downlinks

Downlinks are messages sent from KPN Things to a device. The API provides two main approaches to sending downlinks:

1. **Actuator-style downlinks (recommended for most cases)**
   * Use the `/downlinks` resource.
   * You provide a high-level command, and KPN Things translates it into the correct low-level protocol format using the configured encoder for your device.
   * This approach is safer and easier to use, since KPN Things handles protocol-specific details.
2. **Connection-specific downlinks (advanced usage)**
   * Use protocol-specific APIs such as `/http/downlinks`, `/mqtt/downlinks`, `/sms/downlinks`, `/lora/downlinks`, or `/digitalmatter/downlinks`.
   * You send downlink payloads in the native format of the underlying connection type.
   * This allows greater flexibility but comes with risks: you may send commands that disrupt device operation (for example, disabling communication). Use these APIs only when actuator-style downlinks do not meet your requirements.

### **Choosing the Right API**

* **Use actuator-style downlinks** whenever possible. They are protocol-agnostic, simpler, and safer.
* **Use connection-specific APIs** if you need full control over the payload format or protocol-specific features.

***

## Actuator-Style Downlinks

Download the `/downlinks` [specification](https://api.kpnthings.com/openapi-specifications/downlinks)

## GET /downlinks

> Retrieve downlinks filtered and sorted by specified search and sort criteria

```json
{"openapi":"3.1.0","info":{"title":"Things Downlinks API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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"}}},"schemas":{"PageOfDownlinks":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Downlink"}}}}],"description":"A paginated list of downlinks","title":"PageOfDownlinks"},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{}},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page."},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page."}},"required":["items"],"title":"Page"},"Downlink":{"type":"object","description":"A message that is sent to an IoT device.","properties":{"id":{"type":"string","description":"Unique identifier for the downlink.","readOnly":true},"networkId":{"type":"string","description":"An identifier for a device that is on an activated network."},"externalReference":{"type":"string","description":"Optional external identifier that can be provided by API caller to reference the downlink with. Must be unique for the client that owns the device."},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"message":{"type":"string","description":"SenML message to send to the device"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink is created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink is last modified in the system.","readOnly":true},"logs":{"type":"array","description":"Logs of downlink message","items":{"$ref":"#/components/schemas/DownlinkLog"}}},"required":["networkId","status"],"title":"Downlink"},"DownlinkStatus":{"type":"string","description":"Status of the downlink message. Known values include: PENDING, EXECUTING, SENT_TO_CARRIER, CANCELLED, RETRY, DELIVERED and FAILED","title":"DownlinkStatus"},"DownlinkLog":{"type":"object","description":"Log entry that describes a status change or operation that happened with respect to the downlink","properties":{"createdAt":{"type":"string","format":"date-time","description":"The creation timestamp of the downlink log"},"event":{"$ref":"#/components/schemas/DownlinkEventType"},"errorCode":{"type":"string","description":"Error code indicating the reason for a failure, if applicable.","pattern":".*\\S.*"}},"required":["createdAt"],"title":"DownlinkLog"},"DownlinkEventType":{"type":"string","description":"Name of the event which corresponds to this log entry. Known values include: DOWNLINK_PART_SENT, DOWNLINK_PART_FAILED, DOWNLINK_PART_DELIVERED, DOWNLINK_ACCEPTED, DOWNLINK_REJECTED, DOWNLINK_STARTED, DOWNLINK_DELIVERED and DOWNLINK_FAILED","title":"DownlinkEventType"}}},"paths":{"/downlinks":{"get":{"summary":"Retrieve downlinks filtered and sorted by specified search and sort criteria","operationId":"searchDownlinks","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"q","in":"query","description":"Include only downlinks whose tagValue, networkId or message match the search term. The tagValue must match exactly. The networkId and message may match partially. Matching for every query parameter is done case-sensitively.","style":"form","explode":true,"schema":{"type":"string","minLength":1}},{"name":"createdBefore","in":"query","description":"Include only downlinks 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"}},{"name":"createdSince","in":"query","description":"Include only downlinks 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"}},{"name":"modifiedBefore","in":"query","description":"Include only downlinks 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"}},{"name":"modifiedSince","in":"query","description":"Include only downlinks 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"}}],"responses":{"200":{"description":"Page of filtered downlinks. Only downlinks that are accessible to the caller are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfDownlinks"}}}}}}}}}
```

## POST /downlinks

> Create a new downlink

```json
{"openapi":"3.1.0","info":{"title":"Things Downlinks API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CreateDownlinkRequest":{"type":"object","description":"A request to create a downlink to be sent to an IoT device.","properties":{"externalReference":{"type":"string","description":"Optional external identifier that can be provided by API caller to reference the downlink with. Must be unique for the client that owns the device."},"instruction":{"allOf":[{"$ref":"#/components/schemas/SenMLPack"},{"description":"Instruction in SenML format to send to the device. The provided instruction must contain a bn that identifies the device. The SenML instruction will be transformed into a protocol specific downlink using the configured encoder."}]},"method":{"type":"object","discriminator":{"propertyName":"protocol","mapping":{"HTTP":"#/components/schemas/HttpMethod","LORA":"#/components/schemas/LoraMethod","MQTT":"#/components/schemas/MqttMethod","SMS":"#/components/schemas/SmsMethod"}},"oneOf":[{"$ref":"#/components/schemas/HttpMethod"},{"$ref":"#/components/schemas/LoraMethod"},{"$ref":"#/components/schemas/MqttMethod"},{"$ref":"#/components/schemas/SmsMethod"}]},"retryLimit":{"type":"integer","default":0,"description":"The maximum number of retries that should be performed for the downlink.","minimum":0},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."}},"required":["instruction","method"],"title":"CreateDownlinkRequest"},"SenMLPack":{"type":"array","items":{"$ref":"#/components/schemas/SenMLRecord"},"title":"SenMLPack"},"SenMLRecord":{"type":"object","description":"A single record in a SenML pack.","properties":{"i_":{"type":"number","format":"int32"},"bn":{"type":"string"},"bt":{"type":"number","format":"double"},"bv":{"type":"number","format":"double"},"bs":{"type":"number","format":"double"},"bu":{"type":"string"},"bver":{"type":"integer","format":"int32"},"l":{"type":"string"},"n":{"type":"string"},"s":{"type":"number","format":"double"},"t":{"type":"number","format":"double"},"u":{"type":"string"},"ut":{"type":"number","format":"double"},"v":{"type":"number","format":"double"},"vb":{"type":"boolean"},"vs":{"type":"string"},"vd":{"type":"string"}},"title":"SenMLRecord"},"HttpMethod":{"type":"object","description":"Method of delivering a downlink over HTTP.","properties":{"protocol":{"type":"string","description":"The protocol type. For HttpMethod, this must be HTTP."}},"required":["protocol"],"title":"HttpMethod"},"LoraMethod":{"type":"object","description":"Method of delivering a downlink using the LoRa protocol.","properties":{"protocol":{"type":"string","description":"The protocol type. For LoraMethod, this must be LORA."},"fPort":{"type":"integer","description":"LoRaWAN FPort used by the device for this downlink."}},"required":["protocol"],"title":"LoraMethod"},"MqttMethod":{"type":"object","description":"Method of delivering a downlink using the MQTT protocol.","properties":{"protocol":{"type":"string","description":"The protocol type. For MqttMethod, this must be MQTT."},"topic":{"type":"string","default":"downlink","description":"MQTT topic to which the message should be published."},"contentType":{"type":"string","description":"MIME type of the message content."}},"required":["protocol"],"title":"MqttMethod"},"SmsMethod":{"type":"object","description":"Method of delivering a downlink by SMS","properties":{"protocol":{"type":"string","description":"The protocol type. For SmsMethod, this must be SMS."}},"required":["protocol"],"title":"SmsMethod"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"Downlink":{"type":"object","description":"A message that is sent to an IoT device.","properties":{"id":{"type":"string","description":"Unique identifier for the downlink.","readOnly":true},"networkId":{"type":"string","description":"An identifier for a device that is on an activated network."},"externalReference":{"type":"string","description":"Optional external identifier that can be provided by API caller to reference the downlink with. Must be unique for the client that owns the device."},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"message":{"type":"string","description":"SenML message to send to the device"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink is created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink is last modified in the system.","readOnly":true},"logs":{"type":"array","description":"Logs of downlink message","items":{"$ref":"#/components/schemas/DownlinkLog"}}},"required":["networkId","status"],"title":"Downlink"},"DownlinkStatus":{"type":"string","description":"Status of the downlink message. Known values include: PENDING, EXECUTING, SENT_TO_CARRIER, CANCELLED, RETRY, DELIVERED and FAILED","title":"DownlinkStatus"},"DownlinkLog":{"type":"object","description":"Log entry that describes a status change or operation that happened with respect to the downlink","properties":{"createdAt":{"type":"string","format":"date-time","description":"The creation timestamp of the downlink log"},"event":{"$ref":"#/components/schemas/DownlinkEventType"},"errorCode":{"type":"string","description":"Error code indicating the reason for a failure, if applicable.","pattern":".*\\S.*"}},"required":["createdAt"],"title":"DownlinkLog"},"DownlinkEventType":{"type":"string","description":"Name of the event which corresponds to this log entry. Known values include: DOWNLINK_PART_SENT, DOWNLINK_PART_FAILED, DOWNLINK_PART_DELIVERED, DOWNLINK_ACCEPTED, DOWNLINK_REJECTED, DOWNLINK_STARTED, DOWNLINK_DELIVERED and DOWNLINK_FAILED","title":"DownlinkEventType"}}},"paths":{"/downlinks":{"post":{"summary":"Create a new downlink","operationId":"createDownlink","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDownlinkRequest"}}}},"responses":{"201":{"description":"Downlink has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Downlink"}}}}}}}}}
```

## GET /downlinks/{downlinkId}

> Retrieve a downlink by ID.

```json
{"openapi":"3.1.0","info":{"title":"Things Downlinks API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Downlink":{"type":"object","description":"A message that is sent to an IoT device.","properties":{"id":{"type":"string","description":"Unique identifier for the downlink.","readOnly":true},"networkId":{"type":"string","description":"An identifier for a device that is on an activated network."},"externalReference":{"type":"string","description":"Optional external identifier that can be provided by API caller to reference the downlink with. Must be unique for the client that owns the device."},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"message":{"type":"string","description":"SenML message to send to the device"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink is created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink is last modified in the system.","readOnly":true},"logs":{"type":"array","description":"Logs of downlink message","items":{"$ref":"#/components/schemas/DownlinkLog"}}},"required":["networkId","status"],"title":"Downlink"},"DownlinkStatus":{"type":"string","description":"Status of the downlink message. Known values include: PENDING, EXECUTING, SENT_TO_CARRIER, CANCELLED, RETRY, DELIVERED and FAILED","title":"DownlinkStatus"},"DownlinkLog":{"type":"object","description":"Log entry that describes a status change or operation that happened with respect to the downlink","properties":{"createdAt":{"type":"string","format":"date-time","description":"The creation timestamp of the downlink log"},"event":{"$ref":"#/components/schemas/DownlinkEventType"},"errorCode":{"type":"string","description":"Error code indicating the reason for a failure, if applicable.","pattern":".*\\S.*"}},"required":["createdAt"],"title":"DownlinkLog"},"DownlinkEventType":{"type":"string","description":"Name of the event which corresponds to this log entry. Known values include: DOWNLINK_PART_SENT, DOWNLINK_PART_FAILED, DOWNLINK_PART_DELIVERED, DOWNLINK_ACCEPTED, DOWNLINK_REJECTED, DOWNLINK_STARTED, DOWNLINK_DELIVERED and DOWNLINK_FAILED","title":"DownlinkEventType"}}},"paths":{"/downlinks/{downlinkId}":{"get":{"summary":"Retrieve a downlink by ID.","operationId":"getDownlink","parameters":[{"name":"downlinkId","in":"path","description":"Downlink identifier","required":true,"style":"simple","schema":{"type":"string"}}],"responses":{"200":{"description":"Downlink has been successfully fetched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Downlink"}}}}}}}}}
```

## DELETE /downlinks/{downlinkId}

> Accepts and schedules full or partial cancellation of downlink for further downstream handling.

```json
{"openapi":"3.1.0","info":{"title":"Things Downlinks API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.delete"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}}},"paths":{"/downlinks/{downlinkId}":{"delete":{"summary":"Accepts and schedules full or partial cancellation of downlink for further downstream handling.","operationId":"cancelDownlink","parameters":[{"name":"downlinkId","in":"path","description":"Downlink identifier","required":true,"style":"simple","schema":{"type":"string"}},{"name":"forced","in":"query","description":"Whether to force the cancellation of the downlink or not.","style":"form","explode":true,"schema":{"type":"boolean","default":false}}],"responses":{"202":{"description":"Downlink cancellation has been accepted and scheduled for further downstream processing."},"409":{"description":"Downlink status does not permit cancellation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```

***

## HTTP Downlinks

Download the `/http/downlinks` [specification](https://api.kpnthings.com/openapi-specifications/http-downlinks)

## GET /http/downlinks

> Retrieve HTTP downlinks filtered and sorted by specified search and sort criteria

```json
{"openapi":"3.1.0","info":{"title":"Things HTTP Downlinks API","version":"0.6.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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"}}},"schemas":{"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","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","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"PageOfHttpDownlinks":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/HttpDownlink"}}}}],"description":"A paginated list of HTTP downlinks.","title":"PageOfHttpDownlinks"},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{}},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page."},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page."}},"required":["items"],"title":"Page"},"HttpDownlink":{"type":"object","description":"A downlink that is sent to an HTTP device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/HttpMessage"},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"HttpDownlink"},"HttpMessage":{"type":"object","description":"The message of the HTTP downlink.","discriminator":{"propertyName":"type","mapping":{"binary":"#/components/schemas/HttpBinaryMessage","text":"#/components/schemas/HttpTextMessage"}},"oneOf":[{"$ref":"#/components/schemas/HttpBinaryMessage"},{"$ref":"#/components/schemas/HttpTextMessage"}],"title":"HttpMessage"},"HttpBinaryMessage":{"type":"object","properties":{"type":{"type":"string"},"body":{"allOf":[{"$ref":"#/components/schemas/Base64String"},{"description":"Binary message body encoded in base64"}]},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers to include on downlink message"}},"required":["body","type"],"title":"HttpBinaryMessage"},"Base64String":{"type":"string","format":"byte","contentEncoding":"base64","description":"Base64 encoded binary string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"},"HttpTextMessage":{"type":"object","properties":{"type":{"type":"string"},"body":{"type":"string","description":"UTF-8 message body"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers to include on downlink message"}},"required":["body","type"],"title":"HttpTextMessage"},"DownlinkStatus":{"type":"string","description":"The status of the downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the HTTP downlink. Known values include: CANCELLED, TIMEOUT and EVICTED","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/http/downlinks":{"get":{"summary":"Retrieve HTTP downlinks filtered and sorted by specified search and sort criteria","operationId":"searchDownlinks","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"deviceId","in":"query","description":"Include only downlinks for the device with the provided deviceId. The deviceId must match exactly.","style":"form","explode":true,"schema":{"$ref":"#/components/schemas/DeviceId"}},{"name":"createdBefore","in":"query","description":"Include only HTTP downlinks 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"}},{"name":"createdSince","in":"query","description":"Include only HTTP downlinks 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"}},{"name":"modifiedBefore","in":"query","description":"Include only HTTP downlinks 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"}},{"name":"modifiedSince","in":"query","description":"Include only HTTP downlinks 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"}},{"name":"status","in":"query","description":"Include only HTTP downlinks whose status matches the provided status. The status must match exactly.","style":"form","explode":true,"schema":{"type":"string","enum":["PENDING","EXECUTING","DONE"]}}],"responses":{"200":{"description":"Page of filtered HTTP downlinks. Only downlinks that are accessible to the caller are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfHttpDownlinks"}}}}}}}}}
```

## POST /http/downlinks

> Create a new HTTP downlink

```json
{"openapi":"3.1.0","info":{"title":"Things HTTP Downlinks API","version":"0.6.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"HttpDownlink":{"type":"object","description":"A downlink that is sent to an HTTP device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/HttpMessage"},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"HttpDownlink"},"HttpMessage":{"type":"object","description":"The message of the HTTP downlink.","discriminator":{"propertyName":"type","mapping":{"binary":"#/components/schemas/HttpBinaryMessage","text":"#/components/schemas/HttpTextMessage"}},"oneOf":[{"$ref":"#/components/schemas/HttpBinaryMessage"},{"$ref":"#/components/schemas/HttpTextMessage"}],"title":"HttpMessage"},"HttpBinaryMessage":{"type":"object","properties":{"type":{"type":"string"},"body":{"allOf":[{"$ref":"#/components/schemas/Base64String"},{"description":"Binary message body encoded in base64"}]},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers to include on downlink message"}},"required":["body","type"],"title":"HttpBinaryMessage"},"Base64String":{"type":"string","format":"byte","contentEncoding":"base64","description":"Base64 encoded binary string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"},"HttpTextMessage":{"type":"object","properties":{"type":{"type":"string"},"body":{"type":"string","description":"UTF-8 message body"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers to include on downlink message"}},"required":["body","type"],"title":"HttpTextMessage"},"DownlinkStatus":{"type":"string","description":"The status of the downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","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","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the HTTP downlink. Known values include: CANCELLED, TIMEOUT and EVICTED","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/http/downlinks":{"post":{"summary":"Create a new HTTP downlink","operationId":"createDownlink","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpDownlink"}}}},"responses":{"201":{"description":"HTTP downlink has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpDownlink"}}}}}}}}}
```

## GET /http/downlinks/{downlinkId}

> Retrieve a specific HTTP downlink by its ID

```json
{"openapi":"3.1.0","info":{"title":"Things HTTP Downlinks API","version":"0.6.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"HttpDownlink":{"type":"object","description":"A downlink that is sent to an HTTP device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/HttpMessage"},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"HttpDownlink"},"HttpMessage":{"type":"object","description":"The message of the HTTP downlink.","discriminator":{"propertyName":"type","mapping":{"binary":"#/components/schemas/HttpBinaryMessage","text":"#/components/schemas/HttpTextMessage"}},"oneOf":[{"$ref":"#/components/schemas/HttpBinaryMessage"},{"$ref":"#/components/schemas/HttpTextMessage"}],"title":"HttpMessage"},"HttpBinaryMessage":{"type":"object","properties":{"type":{"type":"string"},"body":{"allOf":[{"$ref":"#/components/schemas/Base64String"},{"description":"Binary message body encoded in base64"}]},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers to include on downlink message"}},"required":["body","type"],"title":"HttpBinaryMessage"},"Base64String":{"type":"string","format":"byte","contentEncoding":"base64","description":"Base64 encoded binary string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"},"HttpTextMessage":{"type":"object","properties":{"type":{"type":"string"},"body":{"type":"string","description":"UTF-8 message body"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers to include on downlink message"}},"required":["body","type"],"title":"HttpTextMessage"},"DownlinkStatus":{"type":"string","description":"The status of the downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","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","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the HTTP downlink. Known values include: CANCELLED, TIMEOUT and EVICTED","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/http/downlinks/{downlinkId}":{"get":{"summary":"Retrieve a specific HTTP downlink by its ID","operationId":"getDownlink","parameters":[{"name":"downlinkId","in":"path","description":"The ID of the HTTP downlink to retrieve.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The requested HTTP downlink.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpDownlink"}}}}}}}}}
```

## DELETE /http/downlinks/{downlinkId}

> Accepts and schedules full or partial cancellation of a HTTP downlink for further downstream handling.

```json
{"openapi":"3.1.0","info":{"title":"Things HTTP Downlinks API","version":"0.6.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.delete"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}}},"paths":{"/http/downlinks/{downlinkId}":{"delete":{"summary":"Accepts and schedules full or partial cancellation of a HTTP downlink for further downstream handling.","operationId":"cancelDownlink","parameters":[{"name":"downlinkId","in":"path","description":"HTTP downlink identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}},{"name":"forced","in":"query","description":"Whether to force the cancellation of the HTTP downlink or not.","style":"form","explode":true,"schema":{"type":"boolean","default":false}}],"responses":{"202":{"description":"HTTP downlink cancellation has been accepted and scheduled for further downstream processing."},"409":{"description":"HTTP downlink does not permit cancellation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```

***

## LoRa downlinks

Download the `/lora/downlinks` [specification](https://api.kpnthings.com/openapi-specifications/lora-downlinks)

## GET /lora/downlinks

> Retrieve LoRa downlinks filtered and sorted by specified search and sort criteria

```json
{"openapi":"3.1.0","info":{"title":"Things LoRa Downlinks API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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"}}},"schemas":{"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","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","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"PageOfLoraDownlinks":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LoraDownlink"}}}}],"description":"A paginated list of LoRa downlinks.","title":"PageOfLoraDownlinks"},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{}},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page."},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page."}},"required":["items"],"title":"Page"},"LoraDownlink":{"type":"object","description":"A downlink that is sent to a LoRa IoT device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/PayloadHexMessage"},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"retryLimit":{"type":"integer","default":0,"description":"The maximum number of retries that should be performed for the downlink.","minimum":0},"retryCount":{"type":"integer","description":"The number of retries that have been performed for the downlink.","minimum":0,"readOnly":true},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"LoraDownlink"},"PayloadHexMessage":{"type":"object","description":"The message to send to the LoRa device","properties":{"payloadHex":{"type":"string","description":"Hex-encoded payload","pattern":"^[0-9a-fA-F]+$"},"fPort":{"type":"integer","description":"LoRaWAN FPort used by the device for this downlink."}},"required":["fPort","payloadHex"],"title":"PayloadHexMessage"},"DownlinkStatus":{"type":"string","description":"The status of the LoRa downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the LoRa downlink. Known values include: CANCELLED, FEEDBACK_TIMEOUT, NOT_ACKNOWLEDGED_BY_DEVICE, FAILED_TO_TRANSMIT_TO_DEVICE, FAILED_TO_ENQUEUE_FOR_TRANSMISSION and EVICTED","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/lora/downlinks":{"get":{"summary":"Retrieve LoRa downlinks filtered and sorted by specified search and sort criteria","operationId":"searchDownlinks","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"deviceId","in":"query","description":"Include only downlinks for the device with the provided deviceId. The deviceId must match exactly.","style":"form","explode":true,"schema":{"$ref":"#/components/schemas/DeviceId"}},{"name":"createdBefore","in":"query","description":"Include only LoRa downlinks 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"}},{"name":"createdSince","in":"query","description":"Include only LoRa downlinks 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"}},{"name":"modifiedBefore","in":"query","description":"Include only LoRa downlinks 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"}},{"name":"modifiedSince","in":"query","description":"Include only LoRa downlinks modified at of 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"}},{"name":"status","in":"query","description":"Include only LoRa downlinks whose status matches the provided status. The status must match exactly.","style":"form","explode":true,"schema":{"type":"string","enum":["PENDING","EXECUTING","DONE"]}}],"responses":{"200":{"description":"Page of filtered LoRa downlinks. Only downlinks that are accessible to the caller are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfLoraDownlinks"}}}}}}}}}
```

## POST /lora/downlinks

> Create a new LoRa downlink

```json
{"openapi":"3.1.0","info":{"title":"Things LoRa Downlinks API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"LoraDownlink":{"type":"object","description":"A downlink that is sent to a LoRa IoT device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/PayloadHexMessage"},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"retryLimit":{"type":"integer","default":0,"description":"The maximum number of retries that should be performed for the downlink.","minimum":0},"retryCount":{"type":"integer","description":"The number of retries that have been performed for the downlink.","minimum":0,"readOnly":true},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"LoraDownlink"},"PayloadHexMessage":{"type":"object","description":"The message to send to the LoRa device","properties":{"payloadHex":{"type":"string","description":"Hex-encoded payload","pattern":"^[0-9a-fA-F]+$"},"fPort":{"type":"integer","description":"LoRaWAN FPort used by the device for this downlink."}},"required":["fPort","payloadHex"],"title":"PayloadHexMessage"},"DownlinkStatus":{"type":"string","description":"The status of the LoRa downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","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","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the LoRa downlink. Known values include: CANCELLED, FEEDBACK_TIMEOUT, NOT_ACKNOWLEDGED_BY_DEVICE, FAILED_TO_TRANSMIT_TO_DEVICE, FAILED_TO_ENQUEUE_FOR_TRANSMISSION and EVICTED","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/lora/downlinks":{"post":{"summary":"Create a new LoRa downlink","operationId":"createDownlink","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoraDownlink"}}}},"responses":{"201":{"description":"LoRa downlink has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoraDownlink"}}}}}}}}}
```

## GET /lora/downlinks/{downlinkId}

> Retrieve a LoRa downlink by ID

```json
{"openapi":"3.1.0","info":{"title":"Things LoRa Downlinks API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"LoraDownlink":{"type":"object","description":"A downlink that is sent to a LoRa IoT device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/PayloadHexMessage"},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"retryLimit":{"type":"integer","default":0,"description":"The maximum number of retries that should be performed for the downlink.","minimum":0},"retryCount":{"type":"integer","description":"The number of retries that have been performed for the downlink.","minimum":0,"readOnly":true},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"LoraDownlink"},"PayloadHexMessage":{"type":"object","description":"The message to send to the LoRa device","properties":{"payloadHex":{"type":"string","description":"Hex-encoded payload","pattern":"^[0-9a-fA-F]+$"},"fPort":{"type":"integer","description":"LoRaWAN FPort used by the device for this downlink."}},"required":["fPort","payloadHex"],"title":"PayloadHexMessage"},"DownlinkStatus":{"type":"string","description":"The status of the LoRa downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","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","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the LoRa downlink. Known values include: CANCELLED, FEEDBACK_TIMEOUT, NOT_ACKNOWLEDGED_BY_DEVICE, FAILED_TO_TRANSMIT_TO_DEVICE, FAILED_TO_ENQUEUE_FOR_TRANSMISSION and EVICTED","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/lora/downlinks/{downlinkId}":{"get":{"summary":"Retrieve a LoRa downlink by ID","operationId":"getDownlink","parameters":[{"name":"downlinkId","in":"path","description":"LoRa downlink identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The LoRa downlink.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoraDownlink"}}}}}}}}}
```

## DELETE /lora/downlinks/{downlinkId}

> Accepts and schedules full or partial cancellation of a LoRa downlink for further downstream handling.

```json
{"openapi":"3.1.0","info":{"title":"Things LoRa Downlinks API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.delete"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}}},"paths":{"/lora/downlinks/{downlinkId}":{"delete":{"summary":"Accepts and schedules full or partial cancellation of a LoRa downlink for further downstream handling.","operationId":"cancelDownlink","parameters":[{"name":"downlinkId","in":"path","description":"LoRa downlink identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}},{"name":"forced","in":"query","description":"Whether to force the cancellation of the LoRa downlink or not.","style":"form","explode":true,"schema":{"type":"boolean","default":false}}],"responses":{"202":{"description":"LoRa downlink cancellation has been accepted and scheduled for further downstream processing."},"409":{"description":"LoRa downlink status does not permit cancellation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```

## SMS Downlinks

Download the `/sms/downlinks` [specification](https://api.kpnthings.com/openapi-specifications/sms-downlinks)

## GET /sms/downlinks

> Retrieve SMS downlinks filtered and sorted by specified search and sort criteria

```json
{"openapi":"3.1.0","info":{"title":"Things SMS Downlinks API","version":"0.3.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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"}}},"schemas":{"DownlinkStatus":{"type":"string","description":"The status of the downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"PageOfSmsDownlinks":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SmsDownlink"}}}}],"description":"A paginated list of SMS downlinks.","title":"PageOfSmsDownlinks"},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{}},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page."},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page."}},"required":["items"],"title":"Page"},"SmsDownlink":{"type":"object","description":"A downlink that is sent to a mobile device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/SmsMessage"},"iccId":{"type":"string","description":"The ICCID of the SIM card in the mobile device.","readOnly":true},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"deviceId":{"type":"string","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"retryLimit":{"type":"integer","default":0,"description":"The maximum number of retries that should be performed for the downlink.","minimum":0},"retryCount":{"type":"integer","description":"The number of retries that have been performed for the downlink.","minimum":0,"readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"SmsDownlink"},"SmsMessage":{"type":"object","description":"The message to send to the mobile device","properties":{"smsMessageId":{"type":"integer","format":"int64","description":"Unique identifier for the message.","readOnly":true},"text":{"type":"string","description":"The text message"}},"required":["text"],"title":"PayloadMessage"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the SMS downlink. Known values include: CANCELLED, FAILURE_TO_TRANSMIT_TO_DEVICE, FAILURE_TO_ENQUEUE_FOR_TRANSMISSION, FEEDBACK_TIMEOUT and EVICTED","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/sms/downlinks":{"get":{"summary":"Retrieve SMS downlinks filtered and sorted by specified search and sort criteria","operationId":"searchDownlinks","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"deviceId","in":"query","description":"Include only downlinks for the device with the provided deviceId. The deviceId must match exactly.","style":"form","explode":true,"schema":{"type":"string","format":"uuid"}},{"name":"createdBefore","in":"query","description":"Include only SMS downlinks 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"}},{"name":"createdSince","in":"query","description":"Include only SMS downlinks 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"}},{"name":"modifiedBefore","in":"query","description":"Include only SMS downlinks 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"}},{"name":"modifiedSince","in":"query","description":"Include only SMS downlinks modified at of 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"}},{"name":"status","in":"query","description":"Include only SMS downlinks whose status matches the provided status. The status must match exactly.","style":"form","explode":true,"schema":{"$ref":"#/components/schemas/DownlinkStatus"}}],"responses":{"200":{"description":"Page of filtered SMS downlinks. Only downlinks that are accessible to the caller are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfSmsDownlinks"}}}}}}}}}
```

## POST /sms/downlinks

> Create a new SMS downlink

```json
{"openapi":"3.1.0","info":{"title":"Things SMS Downlinks API","version":"0.3.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SmsDownlink":{"type":"object","description":"A downlink that is sent to a mobile device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/SmsMessage"},"iccId":{"type":"string","description":"The ICCID of the SIM card in the mobile device.","readOnly":true},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"deviceId":{"type":"string","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"retryLimit":{"type":"integer","default":0,"description":"The maximum number of retries that should be performed for the downlink.","minimum":0},"retryCount":{"type":"integer","description":"The number of retries that have been performed for the downlink.","minimum":0,"readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"SmsDownlink"},"SmsMessage":{"type":"object","description":"The message to send to the mobile device","properties":{"smsMessageId":{"type":"integer","format":"int64","description":"Unique identifier for the message.","readOnly":true},"text":{"type":"string","description":"The text message"}},"required":["text"],"title":"PayloadMessage"},"DownlinkStatus":{"type":"string","description":"The status of the downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the SMS downlink. Known values include: CANCELLED, FAILURE_TO_TRANSMIT_TO_DEVICE, FAILURE_TO_ENQUEUE_FOR_TRANSMISSION, FEEDBACK_TIMEOUT and EVICTED","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/sms/downlinks":{"post":{"summary":"Create a new SMS downlink","operationId":"createDownlink","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsDownlink"}}}},"responses":{"201":{"description":"SMS downlink has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsDownlink"}}}}}}}}}
```

## GET /sms/downlinks/{downlinkId}

> Retrieve an SMS downlink by ID

```json
{"openapi":"3.1.0","info":{"title":"Things SMS Downlinks API","version":"0.3.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SmsDownlink":{"type":"object","description":"A downlink that is sent to a mobile device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/SmsMessage"},"iccId":{"type":"string","description":"The ICCID of the SIM card in the mobile device.","readOnly":true},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"deviceId":{"type":"string","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"retryLimit":{"type":"integer","default":0,"description":"The maximum number of retries that should be performed for the downlink.","minimum":0},"retryCount":{"type":"integer","description":"The number of retries that have been performed for the downlink.","minimum":0,"readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Indicates if this is a dry run."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"SmsDownlink"},"SmsMessage":{"type":"object","description":"The message to send to the mobile device","properties":{"smsMessageId":{"type":"integer","format":"int64","description":"Unique identifier for the message.","readOnly":true},"text":{"type":"string","description":"The text message"}},"required":["text"],"title":"PayloadMessage"},"DownlinkStatus":{"type":"string","description":"The status of the downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the SMS downlink. Known values include: CANCELLED, FAILURE_TO_TRANSMIT_TO_DEVICE, FAILURE_TO_ENQUEUE_FOR_TRANSMISSION, FEEDBACK_TIMEOUT and EVICTED","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/sms/downlinks/{downlinkId}":{"get":{"summary":"Retrieve an SMS downlink by ID","operationId":"getDownlink","parameters":[{"name":"downlinkId","in":"path","description":"SMS downlink identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The SMS downlink.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsDownlink"}}}}}}}}}
```

## DELETE /sms/downlinks/{downlinkId}

> Accepts and schedules full or partial cancellation of a SMS downlink for further downstream handling.

```json
{"openapi":"3.1.0","info":{"title":"Things SMS Downlinks API","version":"0.3.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.delete"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}}},"paths":{"/sms/downlinks/{downlinkId}":{"delete":{"summary":"Accepts and schedules full or partial cancellation of a SMS downlink for further downstream handling.","operationId":"cancelDownlink","parameters":[{"name":"downlinkId","in":"path","description":"SMS downlink identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}},{"name":"forced","in":"query","description":"Whether to force the cancellation of the SMS downlink or not.","style":"form","explode":true,"schema":{"type":"boolean","default":false}}],"responses":{"202":{"description":"SMS downlink cancellation has been accepted and scheduled for further downstream processing."},"409":{"description":"SMS downlink status does not permit cancellation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```

***

## MQTT Downlinks

Download the `/mqtt/downlinks` [specification](https://api.kpnthings.com/openapi-specifications/mqtt-downlinks)

## GET /mqtt/downlinks

> Retrieve MQTT downlinks filtered and sorted by specified search and sort criteria

```json
{"openapi":"3.1.0","info":{"title":"Things MQTT Downlinks API","version":"0.10.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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"}}},"schemas":{"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","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","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"DownlinkStatus":{"type":"string","description":"The status of the downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"PageOfMqttDownlinks":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MqttDownlink"}}}}],"description":"A paginated list of MQTT downlinks.","title":"PageOfDownlinks"},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{}},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page."},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page."}},"required":["items"],"title":"Page"},"MqttDownlink":{"type":"object","description":"A downlink that is sent to an MQTT device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/MqttMessage"},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Whether or not this is a 'test' downlink that should not be delivered. If <code>true</code> the system will prevent actual delivery of the downlink to the MQTT account and pretend instead that successful delivery has occurred. This mode may be used to test your configuration within KPN Things without requiring a fully functional MQTT device."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"Downlink"},"MqttMessage":{"type":"object","description":"MQTT message","discriminator":{"propertyName":"type","mapping":{"binary":"#/components/schemas/MqttBinaryMessage","text":"#/components/schemas/MqttTextMessage"}},"oneOf":[{"$ref":"#/components/schemas/MqttBinaryMessage"},{"$ref":"#/components/schemas/MqttTextMessage"}],"properties":{"type":{"type":"string"}},"title":"MqttMessage"},"MqttBinaryMessage":{"type":"object","properties":{"type":{"type":"string"},"payload":{"allOf":[{"$ref":"#/components/schemas/Base64String"},{"description":"Binary payload encoded in base64"}]},"topic":{"type":"string","description":"MQTT topic to which the message should be published"},"contentType":{"type":"string","description":"Type of the message content"},"qos":{"$ref":"#/components/schemas/MqttQualityOfService"}},"required":["payload","topic","type"],"title":"MqttBinaryMessage"},"Base64String":{"type":"string","format":"byte","contentEncoding":"base64","description":"Base64 encoded binary string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"},"MqttQualityOfService":{"type":"string","default":"AT_MOST_ONCE","description":"MQTT quality of service (QoS) level. For details on QoS semantics, refer to: <a href=\"https://mqtt.org/mqtt-specification/\" title=\"The MQTT specifications\">https://mqtt.org/mqtt-specification/</a>. Known values include: AT_MOST_ONCE","title":"MqttQualityOfService"},"MqttTextMessage":{"type":"object","properties":{"type":{"type":"string"},"payload":{"type":"string","description":"UTF-8 text payload"},"topic":{"type":"string","description":"MQTT topic to which the message should be published"},"contentType":{"type":"string","description":"MIME type of the message content (e.g. text/plain)"},"qos":{"$ref":"#/components/schemas/MqttQualityOfService"}},"required":["payload","topic","type"],"title":"MqttTextMessage"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the MQTT downlink. Known values include: CANCELLED, FEEDBACK_TIMEOUT, FAILED_TO_TRANSMIT_TO_DEVICE","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/mqtt/downlinks":{"get":{"summary":"Retrieve MQTT downlinks filtered and sorted by specified search and sort criteria","operationId":"searchDownlinks","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"deviceId","in":"query","description":"Include only downlinks for the device with the provided deviceId. The deviceId must match exactly.","style":"form","explode":true,"schema":{"$ref":"#/components/schemas/DeviceId"}},{"name":"createdBefore","in":"query","description":"Include only MQTT downlinks 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"}},{"name":"createdSince","in":"query","description":"Include only MQTT downlinks 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"}},{"name":"modifiedBefore","in":"query","description":"Include only MQTT downlinks 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"}},{"name":"modifiedSince","in":"query","description":"Include only MQTT downlinks 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"}},{"name":"status","in":"query","description":"Include only MQTT downlinks whose status matches the provided status. The status must match exactly.","style":"form","explode":true,"schema":{"$ref":"#/components/schemas/DownlinkStatus"}}],"responses":{"200":{"description":"Page of filtered MQTT downlinks. Only downlinks that are accessible to the caller are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfMqttDownlinks"}}}}}}}}}
```

## POST /mqtt/downlinks

> Create a new MQTT downlink

```json
{"openapi":"3.1.0","info":{"title":"Things MQTT Downlinks API","version":"0.10.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"MqttDownlink":{"type":"object","description":"A downlink that is sent to an MQTT device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/MqttMessage"},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Whether or not this is a 'test' downlink that should not be delivered. If <code>true</code> the system will prevent actual delivery of the downlink to the MQTT account and pretend instead that successful delivery has occurred. This mode may be used to test your configuration within KPN Things without requiring a fully functional MQTT device."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"Downlink"},"MqttMessage":{"type":"object","description":"MQTT message","discriminator":{"propertyName":"type","mapping":{"binary":"#/components/schemas/MqttBinaryMessage","text":"#/components/schemas/MqttTextMessage"}},"oneOf":[{"$ref":"#/components/schemas/MqttBinaryMessage"},{"$ref":"#/components/schemas/MqttTextMessage"}],"properties":{"type":{"type":"string"}},"title":"MqttMessage"},"MqttBinaryMessage":{"type":"object","properties":{"type":{"type":"string"},"payload":{"allOf":[{"$ref":"#/components/schemas/Base64String"},{"description":"Binary payload encoded in base64"}]},"topic":{"type":"string","description":"MQTT topic to which the message should be published"},"contentType":{"type":"string","description":"Type of the message content"},"qos":{"$ref":"#/components/schemas/MqttQualityOfService"}},"required":["payload","topic","type"],"title":"MqttBinaryMessage"},"Base64String":{"type":"string","format":"byte","contentEncoding":"base64","description":"Base64 encoded binary string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"},"MqttQualityOfService":{"type":"string","default":"AT_MOST_ONCE","description":"MQTT quality of service (QoS) level. For details on QoS semantics, refer to: <a href=\"https://mqtt.org/mqtt-specification/\" title=\"The MQTT specifications\">https://mqtt.org/mqtt-specification/</a>. Known values include: AT_MOST_ONCE","title":"MqttQualityOfService"},"MqttTextMessage":{"type":"object","properties":{"type":{"type":"string"},"payload":{"type":"string","description":"UTF-8 text payload"},"topic":{"type":"string","description":"MQTT topic to which the message should be published"},"contentType":{"type":"string","description":"MIME type of the message content (e.g. text/plain)"},"qos":{"$ref":"#/components/schemas/MqttQualityOfService"}},"required":["payload","topic","type"],"title":"MqttTextMessage"},"DownlinkStatus":{"type":"string","description":"The status of the downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","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","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the MQTT downlink. Known values include: CANCELLED, FEEDBACK_TIMEOUT, FAILED_TO_TRANSMIT_TO_DEVICE","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/mqtt/downlinks":{"post":{"summary":"Create a new MQTT downlink","operationId":"createDownlink","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MqttDownlink"}}}},"responses":{"201":{"description":"MQTT downlink has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MqttDownlink"}}}}}}}}}
```

## GET /mqtt/downlinks/{downlinkId}

> Retrieve a MQTT downlink by ID

```json
{"openapi":"3.1.0","info":{"title":"Things MQTT Downlinks API","version":"0.10.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"MqttDownlink":{"type":"object","description":"A downlink that is sent to an MQTT device.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the downlink.","readOnly":true},"message":{"$ref":"#/components/schemas/MqttMessage"},"status":{"$ref":"#/components/schemas/DownlinkStatus"},"deviceId":{"$ref":"#/components/schemas/DeviceId","description":"The device identifier which this downlink is targeting."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was created in the system.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the downlink was last modified in the system.","readOnly":true},"feedbackTimeout":{"allOf":[{"$ref":"#/components/schemas/SimpleDuration"},{"description":"The duration after which feedback is expected for the downlink. Must be at least 10 minutes."}]},"dryRun":{"type":"boolean","default":false,"description":"Whether or not this is a 'test' downlink that should not be delivered. If <code>true</code> the system will prevent actual delivery of the downlink to the MQTT account and pretend instead that successful delivery has occurred. This mode may be used to test your configuration within KPN Things without requiring a fully functional MQTT device."},"lastFailureReason":{"$ref":"#/components/schemas/DownlinkFailureReason"}},"required":["deviceId","feedbackTimeout","message"],"title":"Downlink"},"MqttMessage":{"type":"object","description":"MQTT message","discriminator":{"propertyName":"type","mapping":{"binary":"#/components/schemas/MqttBinaryMessage","text":"#/components/schemas/MqttTextMessage"}},"oneOf":[{"$ref":"#/components/schemas/MqttBinaryMessage"},{"$ref":"#/components/schemas/MqttTextMessage"}],"properties":{"type":{"type":"string"}},"title":"MqttMessage"},"MqttBinaryMessage":{"type":"object","properties":{"type":{"type":"string"},"payload":{"allOf":[{"$ref":"#/components/schemas/Base64String"},{"description":"Binary payload encoded in base64"}]},"topic":{"type":"string","description":"MQTT topic to which the message should be published"},"contentType":{"type":"string","description":"Type of the message content"},"qos":{"$ref":"#/components/schemas/MqttQualityOfService"}},"required":["payload","topic","type"],"title":"MqttBinaryMessage"},"Base64String":{"type":"string","format":"byte","contentEncoding":"base64","description":"Base64 encoded binary string","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"},"MqttQualityOfService":{"type":"string","default":"AT_MOST_ONCE","description":"MQTT quality of service (QoS) level. For details on QoS semantics, refer to: <a href=\"https://mqtt.org/mqtt-specification/\" title=\"The MQTT specifications\">https://mqtt.org/mqtt-specification/</a>. Known values include: AT_MOST_ONCE","title":"MqttQualityOfService"},"MqttTextMessage":{"type":"object","properties":{"type":{"type":"string"},"payload":{"type":"string","description":"UTF-8 text payload"},"topic":{"type":"string","description":"MQTT topic to which the message should be published"},"contentType":{"type":"string","description":"MIME type of the message content (e.g. text/plain)"},"qos":{"$ref":"#/components/schemas/MqttQualityOfService"}},"required":["payload","topic","type"],"title":"MqttTextMessage"},"DownlinkStatus":{"type":"string","description":"The status of the downlink. Known values include: PENDING, EXECUTING and DONE","readOnly":true,"title":"DownlinkStatus"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","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","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"SimpleDuration":{"type":"string","format":"duration","description":"Duration that supports a subset of ISO 8601, where only days, hours, minutes, and seconds can be specified. Days are treated as exactly 24 hours, thus ignoring daylight savings effects.","pattern":"^P(?:(\\d+D)(T(?:(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)?)|T(\\d+H)?(\\d+M)?(\\d+(\\.\\d{1,9})?S)?)$"},"DownlinkFailureReason":{"type":"string","description":"The failure reason of the MQTT downlink. Known values include: CANCELLED, FEEDBACK_TIMEOUT, FAILED_TO_TRANSMIT_TO_DEVICE","readOnly":true,"title":"DownlinkFailureReason"}}},"paths":{"/mqtt/downlinks/{downlinkId}":{"get":{"summary":"Retrieve a MQTT downlink by ID","operationId":"getDownlink","parameters":[{"name":"downlinkId","in":"path","description":"MQTT downlink identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The created MQTT downlink.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MqttDownlink"}}}}}}}}}
```

## DELETE /mqtt/downlinks/{downlinkId}

> Cancel a MQTT downlink for further downstream handling.

```json
{"openapi":"3.1.0","info":{"title":"Things MQTT Downlinks API","version":"0.10.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["downlink.delete"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}}},"paths":{"/mqtt/downlinks/{downlinkId}":{"delete":{"summary":"Cancel a MQTT downlink for further downstream handling.","operationId":"cancelDownlink","parameters":[{"name":"downlinkId","in":"path","description":"MQTT downlink identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}},{"name":"forced","in":"query","description":"Whether to force the cancellation of the MQTT downlink or not.","style":"form","explode":true,"schema":{"type":"boolean","default":false}}],"responses":{"202":{"description":"MQTT downlink cancellation has been accepted and scheduled for further downstream processing."},"409":{"description":"MQTT downlink status does not permit cancellation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kpnthings.com/kpn-things/general-functions/apis/downlinks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.