swagger: '2.0'
info:
title: The Things Stack — Application Server AppAs EndDeviceRegistry API
version: v3.36
description: The Things Stack is an open-source LoRaWAN Network Server implementation. This OpenAPI was derived from the upstream gRPC-Gateway generated api.swagger.json published by TheThingsNetwork/lorawan-stack v3.36.
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
contact:
name: The Things Industries
url: https://www.thethingsindustries.com
host: eu1.cloud.thethings.industries
basePath: /api/v3
schemes:
- https
consumes:
- application/json
produces:
- application/json
security:
- ApiKeyAuth: []
tags:
- name: EndDeviceRegistry
paths:
/applications/{application_ids.application_id}/devices:
get:
summary: 'List end devices in the given application.
Similar to Get, this selects the fields given by the field mask.
More or less fields may be returned, depending on the rights of the caller.'
operationId: EndDeviceRegistry_List
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v3EndDevices'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: application_ids.application_id
in: path
required: true
type: string
- name: field_mask
description: 'The names of the end device fields that should be returned.
See the API reference for which fields can be returned by the different services.'
in: query
required: false
type: string
- name: order
description: 'Order the results by this field path (must be present in the field mask).
Default ordering is by ID. Prepend with a minus (-) to reverse the order.'
in: query
required: false
type: string
- name: limit
description: Limit the number of results per page.
in: query
required: false
type: integer
format: int64
- name: page
description: Page number for pagination. 0 is interpreted as 1.
in: query
required: false
type: integer
format: int64
tags:
- EndDeviceRegistry
/applications/{application_ids.application_id}/devices/count:
get:
summary: Count end devices in the given application.
operationId: EndDeviceRegistry_Count
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v3CountEndDevicesResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: application_ids.application_id
in: path
required: true
type: string
tags:
- EndDeviceRegistry
/applications/{application_ids.application_id}/devices/filter:
post:
summary: 'List end devices in the given application.
Similar to Get, this selects the fields given by the field mask.
More or less fields may be returned, depending on the rights of the caller.'
operationId: EndDeviceRegistry_List2
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v3EndDevices'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: application_ids.application_id
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/v3EndDeviceRegistryListBody'
tags:
- EndDeviceRegistry
/applications/{application_ids.application_id}/devices/{device_id}:
delete:
summary: Delete the end device with the given IDs.
description: 'Before deleting an end device it first needs to be deleted from the
NsEndDeviceRegistry, the AsEndDeviceRegistry and the JsEndDeviceRegistry.
In addition, if the device claimed on a Join Server, it also needs to be
unclaimed via the DeviceClaimingServer so it can be claimed in the future.
This is NOT done automatically.'
operationId: EndDeviceRegistry_Delete
responses:
'200':
description: A successful response.
schema:
type: object
properties: {}
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: application_ids.application_id
in: path
required: true
type: string
- name: device_id
in: path
required: true
type: string
- name: dev_eui
description: The LoRaWAN DevEUI.
in: query
required: false
type: string
format: string
- name: join_eui
description: The LoRaWAN JoinEUI (AppEUI until LoRaWAN 1.0.3 end devices).
in: query
required: false
type: string
format: string
- name: dev_addr
description: The LoRaWAN DevAddr.
in: query
required: false
type: string
format: string
tags:
- EndDeviceRegistry
/applications/{end_device.ids.application_ids.application_id}/devices:
post:
summary: Create a new end device within an application.
description: 'After registering an end device, it also needs to be registered in
the NsEndDeviceRegistry that is exposed by the Network Server,
the AsEndDeviceRegistry that is exposed by the Application Server,
and the JsEndDeviceRegistry that is exposed by the Join Server.'
operationId: EndDeviceRegistry_Create
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v3EndDevice'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: end_device.ids.application_ids.application_id
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/v3EndDeviceRegistryCreateBody'
tags:
- EndDeviceRegistry
/applications/{end_device.ids.application_ids.application_id}/devices/{end_device.ids.device_id}:
put:
summary: Update the end device, changing the fields specified by the field mask to the provided values.
operationId: EndDeviceRegistry_Update
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v3EndDevice'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: end_device.ids.application_ids.application_id
in: path
required: true
type: string
- name: end_device.ids.device_id
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: '#/definitions/v3EndDeviceRegistryUpdateBody'
tags:
- EndDeviceRegistry
/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}:
get:
summary: 'Get the end device with the given identifiers, selecting the fields specified
in the field mask.
More or less fields may be returned, depending on the rights of the caller.'
operationId: EndDeviceRegistry_Get
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v3EndDevice'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: end_device_ids.application_ids.application_id
in: path
required: true
type: string
- name: end_device_ids.device_id
in: path
required: true
type: string
- name: end_device_ids.dev_eui
description: The LoRaWAN DevEUI.
in: query
required: false
type: string
format: string
- name: end_device_ids.join_eui
description: The LoRaWAN JoinEUI (AppEUI until LoRaWAN 1.0.3 end devices).
in: query
required: false
type: string
format: string
- name: end_device_ids.dev_addr
description: The LoRaWAN DevAddr.
in: query
required: false
type: string
format: string
- name: field_mask
description: 'The names of the end device fields that should be returned.
See the API reference for which fields can be returned by the different services.'
in: query
required: false
type: string
tags:
- EndDeviceRegistry
definitions:
v3ADRAckLimitExponentValue:
type: object
properties:
value:
$ref: '#/definitions/v3ADRAckLimitExponent'
v3LocationSource:
type: string
enum:
- SOURCE_UNKNOWN
- SOURCE_GPS
- SOURCE_REGISTRY
- SOURCE_IP_GEOLOCATION
- SOURCE_WIFI_RSSI_GEOLOCATION
- SOURCE_BT_RSSI_GEOLOCATION
- SOURCE_LORA_RSSI_GEOLOCATION
- SOURCE_LORA_TDOA_GEOLOCATION
- SOURCE_COMBINED_GEOLOCATION
default: SOURCE_UNKNOWN
description: " - SOURCE_UNKNOWN: The source of the location is not known or not set.\n - SOURCE_GPS: The location is determined by GPS.\n - SOURCE_REGISTRY: The location is set in and updated from a registry.\n - SOURCE_IP_GEOLOCATION: The location is estimated with IP geolocation.\n - SOURCE_WIFI_RSSI_GEOLOCATION: The location is estimated with WiFi RSSI geolocation.\n - SOURCE_BT_RSSI_GEOLOCATION: The location is estimated with BT/BLE RSSI geolocation.\n - SOURCE_LORA_RSSI_GEOLOCATION: The location is estimated with LoRa RSSI geolocation.\n - SOURCE_LORA_TDOA_GEOLOCATION: The location is estimated with LoRa TDOA geolocation.\n - SOURCE_COMBINED_GEOLOCATION: The location is estimated by a combination of geolocation sources.\n\nMore estimation methods can be added."
v3MType:
type: string
enum:
- JOIN_REQUEST
- JOIN_ACCEPT
- UNCONFIRMED_UP
- UNCONFIRMED_DOWN
- CONFIRMED_UP
- CONFIRMED_DOWN
- REJOIN_REQUEST
- PROPRIETARY
default: JOIN_REQUEST
v3NetworkIdentifiers:
type: object
properties:
net_id:
type: string
format: string
example: '000013'
description: LoRa Alliance NetID.
ns_id:
type: string
format: string
example: 70B3D57ED000ABCD
description: LoRaWAN NSID (EUI-64) that uniquely identifies the Network Server instance.
tenant_id:
type: string
description: Optional tenant identifier for multi-tenant deployments.
cluster_id:
type: string
description: Cluster identifier of the Network Server.
cluster_address:
type: string
description: Cluster address of the Network Server.
tenant_address:
type: string
description: Optional tenant address for multi-tenant deployments.
description: Identifies a Network Server.
v3ADRSettingsDisabledMode:
type: object
description: 'Configuration options for cases in which ADR is to be disabled
completely.'
v3EndDeviceRegistryUpdateBody:
type: object
properties:
end_device:
type: object
properties:
ids:
type: object
properties:
application_ids:
type: object
dev_eui:
type: string
format: string
example: 70B3D57ED000ABCD
description: The LoRaWAN DevEUI.
join_eui:
type: string
format: string
example: 70B3D57ED000ABCD
description: The LoRaWAN JoinEUI (AppEUI until LoRaWAN 1.0.3 end devices).
dev_addr:
type: string
format: string
example: 2600ABCD
description: The LoRaWAN DevAddr.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
name:
type: string
description: Friendly name of the device. Stored in Entity Registry.
description:
type: string
description: Description of the device. Stored in Entity Registry.
attributes:
type: object
additionalProperties:
type: string
description: Key-value attributes for this end device. Typically used for organizing end devices or for storing integration-specific data. Stored in Entity Registry.
version_ids:
$ref: '#/definitions/v3EndDeviceVersionIdentifiers'
description: Version Identifiers. Stored in Entity Registry, Network Server and Application Server.
service_profile_id:
type: string
description: Default service profile. Stored in Entity Registry.
network_server_address:
type: string
description: 'The address of the Network Server where this device is supposed to be registered.
Stored in Entity Registry and Join Server.
The typical format of the address is "host:port". If the port is omitted,
the normal port inference (with DNS lookup, otherwise defaults) is used.
The connection shall be established with transport layer security (TLS).
Custom certificate authorities may be configured out-of-band.'
network_server_kek_label:
type: string
description: 'The KEK label of the Network Server to use for wrapping network session keys.
Stored in Join Server.'
application_server_address:
type: string
description: 'The address of the Application Server where this device is supposed to be registered.
Stored in Entity Registry and Join Server.
The typical format of the address is "host:port". If the port is omitted,
the normal port inference (with DNS lookup, otherwise defaults) is used.
The connection shall be established with transport layer security (TLS).
Custom certificate authorities may be configured out-of-band.'
application_server_kek_label:
type: string
description: 'The KEK label of the Application Server to use for wrapping the application session key.
Stored in Join Server.'
application_server_id:
type: string
description: 'The AS-ID of the Application Server to use.
Stored in Join Server.'
join_server_address:
type: string
description: 'The address of the Join Server where this device is supposed to be registered.
Stored in Entity Registry.
The typical format of the address is "host:port". If the port is omitted,
the normal port inference (with DNS lookup, otherwise defaults) is used.
The connection shall be established with transport layer security (TLS).
Custom certificate authorities may be configured out-of-band.'
locations:
type: object
additionalProperties:
$ref: '#/definitions/lorawanv3Location'
description: Location of the device. Stored in Entity Registry.
picture:
$ref: '#/definitions/v3Picture'
description: Stored in Entity Registry.
supports_class_b:
type: boolean
description: 'Whether the device supports class B.
Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.'
supports_class_c:
type: boolean
description: 'Whether the device supports class C.
Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.'
lorawan_version:
$ref: '#/definitions/v3MACVersion'
description: 'LoRaWAN MAC version. Stored in Network Server.
Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.'
lorawan_phy_version:
$ref: '#/definitions/v3PHYVersion'
description: 'LoRaWAN PHY version. Stored in Network Server.
Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.'
frequency_plan_id:
type: string
description: 'ID of the frequency plan used by this device.
Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.'
min_frequency:
type: string
format: uint64
description: 'Minimum frequency the device is capable of using (Hz). Stored in Network Server.
Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.'
max_frequency:
type: string
format: uint64
description: 'Maximum frequency the device is capable of using (Hz). Stored in Network Server.
Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.'
supports_join:
type: boolean
description: 'The device supports join (it''s OTAA).
Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.'
resets_join_nonces:
type: boolean
description: 'Whether the device resets the join and dev nonces (not LoRaWAN compliant). Stored in Join Server.
Copied on creation from template identified by version_ids, if any or from the home Network Server device profile, if any.'
root_keys:
$ref: '#/definitions/v3RootKeys'
description: Device root keys. Stored in Join Server.
net_id:
type: string
format: string
example: '000013'
description: Home NetID. Stored in Join Server.
mac_settings:
$ref: '#/definitions/v3MACSettings'
description: 'Settings for how the Network Server handles MAC layer for this device. Stored in Network Server.
Mutually exclusive with MAC settings profile.'
mac_state:
$ref: '#/definitions/v3MACState'
description: MAC state of the device. Stored in Network Server.
pending_mac_state:
$ref: '#/definitions/v3MACState'
description: Pending MAC state of the device. Stored in Network Server.
session:
$ref: '#/definitions/v3Session'
description: Current session of the device. Stored in Network Server and Application Server.
pending_session:
$ref: '#/definitions/v3Session'
description: Pending session. Stored in Network Server and Application Server until RekeyInd is received.
last_dev_nonce:
type: integer
format: int64
description: 'Last DevNonce used.
This field is only used for devices using LoRaWAN version 1.1 and later.
Stored in Join Server.'
used_dev_nonces:
type: array
items:
type: integer
format: int64
description: 'Used DevNonces sorted in ascending order.
This field is only used for devices using LoRaWAN versions preceding 1.1.
Stored in Join Server.'
last_join_nonce:
type: integer
format: int64
description: 'Last JoinNonce/AppNonce(for devices using LoRaWAN versions preceding 1.1) used.
Stored in Join Server.'
last_rj_count_0:
type: integer
format: int64
description: 'Last Rejoin counter value used (type 0/2).
Stored in Join Server.'
last_rj_count_1:
type: integer
format: int64
description: 'Last Rejoin counter value used (type 1).
Stored in Join Server.'
last_dev_status_received_at:
type: string
format: date-time
description: 'Time when last DevStatus MAC command was received.
Stored in Network Server.'
power_state:
$ref: '#/definitions/v3PowerState'
description: 'The power state of the device; whether it is battery-powered or connected to an external power source.
Received via the DevStatus MAC command at status_received_at.
Stored in Network Server.'
battery_percentage:
type: number
format: float
description: 'Latest-known battery percentage of the device.
Received via the DevStatus MAC command at last_dev_status_received_at or earlier.
Stored in Network Server.'
downlink_margin:
type: integer
format: int32
description: 'Demodulation signal-to-noise ratio (dB).
Received via the DevStatus MAC command at last_dev_status_received_at.
Stored in Network Server.'
queued_application_downlinks:
type: array
items:
type: object
$ref: '#/definitions/v3ApplicationDownlink'
description: 'Queued Application downlink messages. Stored in Application Server,
which sets them on the Network Server.
This field is deprecated and is always set equal to session.queued_application_downlinks.'
formatters:
$ref: '#/definitions/v3MessagePayloadFormatters'
description: 'The payload formatters for this end device. Stored in Application Server.
Copied on creation from template identified by version_ids.'
provisioner_id:
type: string
description: ID of the provisioner. Stored in Join Server.
provisioning_data:
type: object
description: Vendor-specific provisioning data. Stored in Join Server.
multicast:
type: boolean
description: Indicates whether this device represents a multicast group.
claim_authentication_code:
$ref: '#/definitions/v3EndDeviceAuthenticationCode'
description: 'Authentication code to claim ownership of the end device.
From TTS v3.21.0 this field is stored in the Identity Server.
For TTS versions < 3.21.0, this field is stored in the Join Server.
The value stored on the Identity Server takes precedence.'
skip_payload_crypto:
type: boolean
description: 'Skip decryption of uplink payloads and encryption of downlink payloads.
This field is deprecated, use skip_payload_crypto_override instead.'
skip_payload_crypto_override:
type: boolean
description: 'Skip decryption of uplink payloads and encryption of downlink payloads.
This field overrides the application-level setting.'
activated_at:
type: string
format: date-time
description: 'Timestamp when the device has been activated. Stored in the Entity Registry.
This field is set by the Application Server when an end device sends
its first uplink.
The Application Server will use the field in order to avoid repeated
calls to the Entity Registry.
The field cannot be unset once set.'
last_seen_at:
type: string
format: date-time
description: 'Timestamp when a device uplink has been last observed.
This field is set by the Application Server and stored in the Identity Server.'
serial_number:
type: string
lora_alliance_profile_ids:
$ref: '#/definitions/v3LoRaAllianceProfileIdentifiers'
mac_settings_profile_ids:
$ref: '#/definitions/v3MACSettingsProfileIdentifiers'
description: 'MAC settings profile identifiers.
Mutually exclusive with MAC settings.'
description: 'Defines an End Device registration and its state on the network.
The persistence of the EndDevice is divided between the Network Server, Application Server and Join Server.
SDKs are responsible for combining (if desired) the three.'
field_mask:
type: string
description: 'The names of the end device fields that should be updated.
See the API reference for which fields can be set on the different services.'
MACCommandRejoinParamSetupAns:
type: object
properties:
max_time_exponent_ack:
type: boolean
MACCommandTxParamSetupReq:
type: object
properties:
max_eirp_index:
$ref: '#/definitions/v3DeviceEIRP'
title: 'Indicates the maximum EIRP value in dBm, indexed by the following vector:
[ 8 10 12 13 14 16 18 20 21 24 26 27 29 30 33 36 ]'
uplink_dwell_time:
type: boolean
downlink_dwell_time:
type: boolean
v3DataRateIndex:
type: string
enum:
- DATA_RATE_0
- DATA_RATE_1
- DATA_RATE_2
- DATA_RATE_3
- DATA_RATE_4
- DATA_RATE_5
- DATA_RATE_6
- DATA_RATE_7
- DATA_RATE_8
- DATA_RATE_9
- DATA_RATE_10
- DATA_RATE_11
- DATA_RATE_12
- DATA_RATE_13
- DATA_RATE_14
- DATA_RATE_15
default: DATA_RATE_0
ADRSettingsDynamicMode:
type: object
properties:
margin:
type: number
format: float
description: 'The ADR margin (dB) tells the network server how much margin it should add in ADR requests.
A bigger margin is less efficient, but gives a better chance of successful reception.
If unset, the default value from Network Server configuration will be used.'
min_data_rate_index:
$ref: '#/definitions/v3DataRateIndexValue'
description: 'Minimum data rate index.
If unset, the default value from Network Server configuration will be used.'
max_data_rate_index:
$ref: '#/definitions/v3DataRateIndexValue'
description: 'Maximum data rate index.
If unset, the default value from Network Server configuration will be used.'
min_tx_power_index:
type: integer
format: int64
description: 'Minimum transmission power index.
If unset, the default value from Network Server configuration will be used.'
max_tx_power_index:
type: integer
format: int64
description: 'Maximum transmission power index.
If unset, the default value from Network Server configuration will be used.'
min_nb_trans:
type: integer
format: int64
description: 'Minimum number of retransmissions.
If unset, the default value from Network Server configuration will be used.'
max_nb_trans:
type: integer
format: int64
description: 'Maximum number of retransmissions.
If unset, the default value from Network Server configuration will be used.'
channel_steering:
$ref: '#/definitions/DynamicModeChannelSteeringSettings'
overrides:
$ref: '#/definitions/DynamicModeOverrides'
description: Configuration options for dynamic ADR.
MACStateDataRateRange:
type: object
properties:
min_data_rate_index:
$ref: '#/definitions/v3DataRateIndex'
max_data_rate_index:
$ref: '#/definitions/v3DataRateIndex'
MACCommandRelayConfAns:
type: object
properties:
second_channel_frequency_ack:
type: boolean
second_channel_ack_offset_ack:
type: boolean
second_channel_data_rate_index_ack:
type: boolean
second_channel_index_ack:
type: boolean
default_channel_index_ack:
type: boolean
cad_periodicity_ack:
type: boolean
v3RelayUplinkForwardingRule:
type: object
properties:
limits:
$ref: '#/definitions/v3RelayUplinkForwardLimits'
description: 'Bucket configuration for the served end device.
If unset, no individual limits will apply to the end device, but the relay global limitations will apply.'
last_w_f_cnt:
type: integer
format: int64
description: Last wake on radio frame counter used by the served end device.
device_id:
type: string
description: End device identifier of the served end device.
session_key_id:
type: string
format: byte
description: Session key ID of the session keys used to derive the root relay session key.
DownlinkMessageMessageMHDR:
type: object
properties:
m_type:
$ref: '#/definitions/v3MType'
v3EndDevice:
type: object
properties:
ids:
$ref: '#/definitions/v3EndDeviceIdentifiers'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
name:
type: string
description: Friendly name of the device. Stored in Entity Registry.
description:
type: string
description: Description of the device. Stored in Entity Registry.
attributes:
type: object
additionalProperties:
type: string
description: Key-value attributes for this end device. Typically used for organizing end devices or for storing integration-specific data. Stored in Entity Registry.
version_ids:
$ref: '#/definitions/v3EndDeviceVersionIdentifiers'
description: Version Identifiers. Stored in Entity Registry, Network Server and Application Server.
service_profile_id:
type: string
description: Default service profile. Stored in Entity Registry.
network_server_address:
type: string
description: 'The address of the Network Server where this device is supposed to be registered.
Stored in Entity Registry and Join Server.
The typical format of the address is "host:port". If the port is omitted,
the normal port inference (with DNS lookup, otherwise defaults) is used.
The connection shall be established with transport layer security (TLS).
Custom certificate authorities may be configured out-of-band.'
network_server_kek_label:
type: string
description: 'The KEK label of the Network Server to use for wrapping network session keys.
Stored in Join Server.'
application_server_address:
type: string
description: 'The address of the Application Server where this device is supposed to be registered.
Stored in Entity Registry and Join Server.
The typical format of the address is "host:port". If the port is omitted,
the normal port inference (with DNS lookup, otherwise defaults) is used.
The connection shall be established with transport layer security (TLS).
Custom certificate authorities may be configured out-of-band.'
application_server_kek_label:
type: string
description: 'The KEK label of the Application Server to use for wrapping the application session key.
Stored in Join Server.'
application_server_id:
type: string
description: 'The AS-ID of the Application Server to use.
Stored in Join Server.'
join_server_address:
type: string
description: 'The address of the Join Server where this device is sup
# --- truncated at 32 KB (138 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/the-things-network/refs/heads/main/openapi/the-things-network-enddeviceregistry-api-openapi.yml