Application Server APIs

List of Application Server APIs.

The As service

Method As.SetLink
Description Set a link configuration from the Application Server a Network Server. This call returns immediately after setting the link configuration; it does not wait for a link to establish. To get link statistics or errors, use GetLinkStats. Note that there can only be one Application Server instance linked to a Network Server for a given application at a time.
Request type SetApplicationLinkRequest
Response type ApplicationLink
HTTP bindings

PUT /api/v3/as/applications/{application_ids.application_id}/link
Method As.GetConfiguration
Request type GetAsConfigurationRequest
Response type GetAsConfigurationResponse
HTTP bindings

GET /api/v3/as/configuration
Method As.GetLink
Description Get a link configuration from the Application Server to Network Server. This only contains the configuration. Use GetLinkStats to view statistics and any link errors.
Request type GetApplicationLinkRequest
Response type ApplicationLink
HTTP bindings

GET /api/v3/as/applications/{application_ids.application_id}/link
Method As.GetLinkStats
Description GetLinkStats returns the link statistics. This call returns a NotFound error code if there is no link for the given application identifiers. This call returns the error code of the link error if linking to a Network Server failed.
Request type ApplicationIdentifiers
Response type ApplicationLinkStats
HTTP bindings

GET /api/v3/as/applications/{application_id}/link/stats
Method As.DeleteLink
Description Delete the link between the Application Server and Network Server for the specified application.
Request type ApplicationIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/as/applications/{application_id}/link

The AppAs service

Method AppAs.DownlinkQueuePush
Description Push downlink messages to the end of the downlink queue.
Request type DownlinkQueueRequest
Response type google.protobuf.Empty
HTTP bindings

POST /api/v3/as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/down/push
Method AppAs.DownlinkQueueReplace
Description Replace the entire downlink queue with the specified messages. This can also be used to empty the queue by specifying no messages.
Request type DownlinkQueueRequest
Response type google.protobuf.Empty
HTTP bindings

POST /api/v3/as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/down/replace
Method AppAs.DownlinkQueueList
Description List the items currently in the downlink queue.
Request type EndDeviceIdentifiers
Response type ApplicationDownlinks
HTTP bindings

GET /api/v3/as/applications/{application_ids.application_id}/devices/{device_id}/down
Method AppAs.DecodeDownlink
Request type DecodeDownlinkRequest
Response type DecodeDownlinkResponse
HTTP bindings

POST /api/v3/as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/down/decode
Method AppAs.DecodeUplink
Request type DecodeUplinkRequest
Response type DecodeUplinkResponse
HTTP bindings

POST /api/v3/as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/up/decode
Method AppAs.EncodeDownlink
Request type EncodeDownlinkRequest
Response type EncodeDownlinkResponse
HTTP bindings

POST /api/v3/as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/down/encode
Method AppAs.GetMQTTConnectionInfo
Description Get connection information to connect an MQTT client.
Request type ApplicationIdentifiers
Response type MQTTConnectionInfo
HTTP bindings

GET /api/v3/as/applications/{application_id}/mqtt-connection-info
Method AppAs.SimulateUplink
Description Simulate an upstream message. This can be used to test integrations.
Request type ApplicationUp
Response type google.protobuf.Empty
HTTP bindings

POST /api/v3/as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/up/simulate
Method AppAs.Subscribe
Description Subscribe to upstream messages.
Request type ApplicationIdentifiers
Response type Stream of ApplicationUp
HTTP bindings

The AppJs service

Method AppJs.GetAppSKey
Description Request the application session key for a particular session.
Request type SessionKeyRequest
Response type AppSKeyResponse
HTTP bindings

The AsJs service

Method AsJs.GetAppSKey
Description Request the application session key for a particular session.
Request type SessionKeyRequest
Response type AppSKeyResponse
HTTP bindings

The AsNs service

Method AsNs.DownlinkQueueReplace
Description Replace the entire downlink queue with the specified messages. This can also be used to empty the queue by specifying no messages. Note that this will trigger an immediate downlink if a downlink slot is available.
Request type DownlinkQueueRequest
Response type google.protobuf.Empty
HTTP bindings
Method AsNs.DownlinkQueuePush
Description Push downlink messages to the end of the downlink queue. Note that this will trigger an immediate downlink if a downlink slot is available.
Request type DownlinkQueueRequest
Response type google.protobuf.Empty
HTTP bindings
Method AsNs.DownlinkQueueList
Description List the items currently in the downlink queue.
Request type EndDeviceIdentifiers
Response type ApplicationDownlinks
HTTP bindings

Messages

Message ApplicationDownlink.ClassBC

Show object example 
{
  "gateways": [],
  "absolute_time": "0001-01-01T00:00:00Z",
}

Fields:

Field gateways
Type repeated ClassBCGatewayIdentifiers
Description

Possible gateway identifiers, antenna index, and group index to use for this downlink message. The Network Server selects one of these gateways for downlink, based on connectivity, signal quality, channel utilization and an available slot. If none of the gateways can be selected, the downlink message fails. If empty, a gateway and antenna is selected automatically from the gateways seen in recent uplinks. If group index is set, gateways will be grouped by the index for the Network Server to select one gateway per group.
Field absolute_time
Type google.protobuf. Timestamp
Description

Absolute time when the downlink message should be transmitted. This requires the gateway to have GPS time synchronization. If the time is in the past or if there is a scheduling conflict, the downlink message fails. If null, the time is selected based on slot availability. This is recommended in class B mode.

Message ApplicationDownlink.ConfirmedRetry

Show object example 
{
  "attempt": 0,
  "max_attempts": null,
}

Fields:

Field attempt
Type uint32
Description

The number of attempted confirmed downlink acknowledgements.
Field max_attempts
Type google.protobuf. UInt32Value
Description

The maximum number of confirmed downlink acknowledgement attempts. If null, the Application Server configuration is used instead.

gt: 0

lte: 100
Show object example 
{
  "session_key_id": "",
  "f_port": 0,
  "f_cnt": 0,
  "frm_payload": "",
  "decoded_payload": {},
  "decoded_payload_warnings": [],
  "confirmed": false,
  "class_b_c": {},
  "priority": "LOWEST",
  "correlation_ids": [],
  "confirmed_retry": {},
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field session_key_id
Type bytes
Description

Join Server issued identifier for the session keys used by this downlink.

max_len: 2048
Field f_port
Type uint32
Description

lte: 255

not_in: [224]
Field f_cnt
Type uint32
Field frm_payload
Type bytes
Description

The frame payload of the downlink message. The payload is encrypted if the skip_payload_crypto field of the EndDevice is true.

max_len: 255
Field decoded_payload
Type google.protobuf. Struct
Description

The decoded frame payload of the downlink message. When scheduling downlink with a message processor configured for the end device (see formatters) or application (see default_formatters), this fields acts as input for the downlink encoder, and the output is set to frm_payload. When reading downlink (listing the queue, downlink message events, etc), this fields acts as output of the downlink decoder, and the input is frm_payload.
Field decoded_payload_warnings
Type repeated string
Description

Warnings generated by the message processor while encoding frm_payload (scheduling downlink) or decoding the frm_payload (reading downlink).
Field confirmed
Type bool
Field class_b_c
Type ApplicationDownlink.ClassBC
Description

Optional gateway and timing information for class B and C. If set, this downlink message will only be transmitted as class B or C downlink. If not set, this downlink message may be transmitted in class A, B and C.
Field priority
Type TxSchedulePriority
Description

Priority for scheduling the downlink message.

defined_only
Field correlation_ids
Type repeated string
Description

max_len: 100
Field confirmed_retry
Type ApplicationDownlink.ConfirmedRetry
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

max_len (value): 200

Message ApplicationDownlinkFailed

Show object example 
{
  "downlink": {},
  "error": {},
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field downlink
Type ApplicationDownlink
Description

required
Field error
Type ErrorDetails
Description

required
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

max_len (value): 200
Show object example 
{
  "downlinks": [],
}

Fields:

Field downlinks
Type repeated ApplicationDownlink
Description

Message ApplicationIdentifiers

Show object example 
{
  "application_id": "",
}

Fields:

Field application_id
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Show object example 
{
  "downlinks": [],
  "last_f_cnt_down": 0,
  "session_key_id": "",
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field downlinks
Type repeated ApplicationDownlink
Description
Field last_f_cnt_down
Type uint32
Field session_key_id
Type bytes
Description

max_len: 2048
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

max_len (value): 200

Message ApplicationJoinAccept

Show object example 
{
  "session_key_id": "",
  "app_s_key": {},
  "invalidated_downlinks": [],
  "pending_session": false,
  "received_at": "0001-01-01T00:00:00Z",
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field session_key_id
Type bytes
Description

Join Server issued identifier for the session keys negotiated in this join.

max_len: 2048
Field app_s_key
Type KeyEnvelope
Description

Encrypted Application Session Key (if Join Server sent it to Network Server).
Field invalidated_downlinks
Type repeated ApplicationDownlink
Description

Downlink messages in the queue that got invalidated because of the session change.
Field pending_session
Type bool
Description

Indicates whether the security context refers to the pending session, i.e. when this join-accept is an answer to a rejoin-request.
Field received_at
Type google.protobuf. Timestamp
Description

Server time when the Network Server received the message.

required
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

max_len (value): 200
Show object example 
{
  "default_formatters": {},
  "skip_payload_crypto": null,
}

Fields:

Field default_formatters
Type MessagePayloadFormatters
Description

Default message payload formatters to use when there are no formatters defined on the end device level.
Field skip_payload_crypto
Type google.protobuf. BoolValue
Description

Skip decryption of uplink payloads and encryption of downlink payloads. Leave empty for the using the Application Server’s default setting.

Message ApplicationLinkStats

Link stats as monitored by the Application Server.

Show object example 
{
  "linked_at": "0001-01-01T00:00:00Z",
  "network_server_address": "",
  "last_up_received_at": "0001-01-01T00:00:00Z",
  "up_count": 0,
  "last_downlink_forwarded_at": "0001-01-01T00:00:00Z",
  "downlink_count": 0,
}

Fields:

Field linked_at
Type google.protobuf. Timestamp
Field network_server_address
Type string
Description

pattern: ^(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*(?:[A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])(?::[0-9]{1,5})?$|^$
Field last_up_received_at
Type google.protobuf. Timestamp
Description

Timestamp when the last upstream message has been received from a Network Server. This can be a join-accept, uplink message or downlink message event.
Field up_count
Type uint64
Description

Number of upstream messages received.
Field last_downlink_forwarded_at
Type google.protobuf. Timestamp
Description

Timestamp when the last downlink message has been forwarded to a Network Server.
Field downlink_count
Type uint64
Description

Number of downlink messages forwarded.

Message ApplicationLocation

Show object example 
{
  "service": "",
  "location": {},
  "attributes": {},
}

Fields:

Field service
Type string
Field location
Type Location
Description

required
Field attributes
Type map of string to string
Description

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

max_len (value): 200

Message ApplicationServiceData

Show object example 
{
  "service": "",
  "data": {},
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field service
Type string
Field data
Type google.protobuf. Struct
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

max_len (value): 200

Message ApplicationUp

Application uplink message.

Restrictions:
  • Only one of uplink_message, uplink_normalized, join_accept, downlink_ack, downlink_nack, downlink_sent, downlink_failed, downlink_queued, downlink_queue_invalidated, location_solved, service_data can be set.
Show object example 
{
  "end_device_ids": {},
  "correlation_ids": [],
  "received_at": "0001-01-01T00:00:00Z",
  "uplink_message": {},
  "uplink_normalized": {},
  "join_accept": {},
  "downlink_ack": {},
  "downlink_nack": {},
  "downlink_sent": {},
  "downlink_failed": {},
  "downlink_queued": {},
  "downlink_queue_invalidated": {},
  "location_solved": {},
  "service_data": {},
  "simulated": false,
}

Fields:

Field end_device_ids
Type EndDeviceIdentifiers
Description

required
Field correlation_ids
Type repeated string
Description

max_len: 100
Field received_at
Type google.protobuf. Timestamp
Description

Server time when the Application Server received the message.
Field uplink_message
Type ApplicationUplink
Field uplink_normalized
Type ApplicationUplinkNormalized
Field join_accept
Type ApplicationJoinAccept
Field downlink_ack
Type ApplicationDownlink
Field downlink_nack
Type ApplicationDownlink
Field downlink_sent
Type ApplicationDownlink
Field downlink_failed
Type ApplicationDownlinkFailed
Field downlink_queued
Type ApplicationDownlink
Field downlink_queue_invalidated
Type ApplicationInvalidatedDownlinks
Field location_solved
Type ApplicationLocation
Field service_data
Type ApplicationServiceData
Field simulated
Type bool
Description

Signals if the message is coming from the Network Server or is simulated. The Application Server automatically sets this field, and callers must not manually set it.
Show object example 
{
  "session_key_id": "",
  "f_port": 0,
  "f_cnt": 0,
  "frm_payload": "",
  "decoded_payload": {},
  "decoded_payload_warnings": [],
  "normalized_payload": [],
  "normalized_payload_warnings": [],
  "rx_metadata": [],
  "settings": {},
  "received_at": "0001-01-01T00:00:00Z",
  "app_s_key": {},
  "last_a_f_cnt_down": 0,
  "confirmed": false,
  "consumed_airtime": "0s",
  "packet_error_rate": 0,
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "last_battery_percentage": {},
  "attributes": {},
}

Fields:

Field session_key_id
Type bytes
Description

Join Server issued identifier for the session keys used by this uplink.

max_len: 2048
Field f_port
Type uint32
Description

LoRaWAN FPort of the uplink message.

lte: 255

not_in: [224]
Field f_cnt
Type uint32
Description

LoRaWAN FCntUp of the uplink message.
Field frm_payload
Type bytes
Description

The frame payload of the uplink message. The payload is still encrypted if the skip_payload_crypto field of the EndDevice is true, which is indicated by the presence of the app_s_key field.
Field decoded_payload
Type google.protobuf. Struct
Description

The decoded frame payload of the uplink message. This field is set by the message processor that is configured for the end device (see formatters) or application (see default_formatters).
Field decoded_payload_warnings
Type repeated string
Description

Warnings generated by the message processor while decoding the frm_payload.
Field normalized_payload
Type repeated google.protobuf. Struct
Description

The normalized frame payload of the uplink message. This field is set by the message processor that is configured for the end device (see formatters) or application (see default_formatters). If the message processor is a custom script, there is no uplink normalizer script and the decoded output is valid normalized payload, this field contains the decoded payload.
Field normalized_payload_warnings
Type repeated string
Description

Warnings generated by the message processor while normalizing the decoded payload.
Field rx_metadata
Type repeated RxMetadata
Description

A list of metadata for each antenna of each gateway that received this message.
Field settings
Type TxSettings
Description

Transmission settings used by the end device.

required
Field received_at
Type google.protobuf. Timestamp
Description

Server time when the Network Server received the message.
Field app_s_key
Type KeyEnvelope
Description

The AppSKey of the current session. This field is only present if the skip_payload_crypto field of the EndDevice is true. Can be used to decrypt uplink payloads and encrypt downlink payloads.
Field last_a_f_cnt_down
Type uint32
Description

The last AFCntDown of the current session. This field is only present if the skip_payload_crypto field of the EndDevice is true. Can be used with app_s_key to encrypt downlink payloads.
Field confirmed
Type bool
Description

Indicates whether the end device used confirmed data uplink.
Field consumed_airtime
Type google.protobuf. Duration
Description

Consumed airtime for the transmission of the uplink message. Calculated by Network Server using the raw payload size and the transmission settings.
Field packet_error_rate
Type float
Description

Packet error rate of the recent uplinks in the current session. Calculated by the Network Server. The value is defined in the [0, 1] interval.
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field last_battery_percentage
Type LastBatteryPercentage
Description

Last battery percentage of the end device. Received via the DevStatus MAC command at last_dev_status_received_at or earlier. Set by the Network Server while handling the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

max_len (value): 200

Message ApplicationUplinkNormalized

Show object example 
{
  "session_key_id": "",
  "f_port": 0,
  "f_cnt": 0,
  "frm_payload": "",
  "normalized_payload": {},
  "normalized_payload_warnings": [],
  "rx_metadata": [],
  "settings": {},
  "received_at": "0001-01-01T00:00:00Z",
  "confirmed": false,
  "consumed_airtime": "0s",
  "locations": {},
  "version_ids": {},
  "network_ids": {},
  "attributes": {},
}

Fields:

Field session_key_id
Type bytes
Description

Join Server issued identifier for the session keys used by this uplink.

max_len: 2048
Field f_port
Type uint32
Description

LoRaWAN FPort of the uplink message.

gte: 1

lte: 255

not_in: [224]
Field f_cnt
Type uint32
Description

LoRaWAN FCntUp of the uplink message.
Field frm_payload
Type bytes
Description

The frame payload of the uplink message. This field is always decrypted with AppSKey.
Field normalized_payload
Type google.protobuf. Struct
Description

The normalized frame payload of the uplink message. This field is set for each item in normalized_payload in the corresponding ApplicationUplink message.

required
Field normalized_payload_warnings
Type repeated string
Description

This field is set to normalized_payload_warnings in the corresponding ApplicationUplink message.
Field rx_metadata
Type repeated RxMetadata
Description

A list of metadata for each antenna of each gateway that received this message.
Field settings
Type TxSettings
Description

Transmission settings used by the end device.

required
Field received_at
Type google.protobuf. Timestamp
Description

Server time when the Network Server received the message.

required
Field confirmed
Type bool
Description

Indicates whether the end device used confirmed data uplink.
Field consumed_airtime
Type google.protobuf. Duration
Description

Consumed airtime for the transmission of the uplink message. Calculated by Network Server using the raw payload size and the transmission settings.
Field locations
Type map of string to Location
Description

End device location metadata, set by the Application Server while handling the message.
Field version_ids
Type EndDeviceVersionIdentifiers
Description

End device version identifiers, set by the Application Server while handling the message.
Field network_ids
Type NetworkIdentifiers
Description

Network identifiers, set by the Network Server that handles the message.
Field attributes
Type map of string to string
Description

Attributes for devices, set by the Application Server while handling the message.

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

max_len (value): 200

Message ClassBCGatewayIdentifiers

Show object example 
{
  "gateway_ids": {},
  "antenna_index": 0,
  "group_index": 0,
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field antenna_index
Type uint32
Field group_index
Type uint32

Message DataRate

Restrictions:
  • Only one of lora, fsk, lrfhss can be set.
Show object example 
{
  "lora": {},
  "fsk": {},
  "lrfhss": {},
}

Fields:

Field lora
Type LoRaDataRate
Field fsk
Type FSKDataRate
Field lrfhss
Type LRFHSSDataRate

Message DecodeDownlinkRequest

Show object example 
{
  "end_device_ids": {},
  "version_ids": {},
  "downlink": {},
  "formatter": "FORMATTER_NONE",
  "parameter": "",
}

Fields:

Field end_device_ids
Type EndDeviceIdentifiers
Description

required
Field version_ids
Type EndDeviceVersionIdentifiers
Field downlink
Type ApplicationDownlink
Description

required
Field formatter
Type PayloadFormatter
Description

defined_only
Field parameter
Type string

Message DecodeUplinkRequest

Show object example 
{
  "end_device_ids": {},
  "version_ids": {},
  "uplink": {},
  "formatter": "FORMATTER_NONE",
  "parameter": "",
}

Fields:

Field end_device_ids
Type EndDeviceIdentifiers
Description

required
Field version_ids
Type EndDeviceVersionIdentifiers
Field uplink
Type ApplicationUplink
Description

required
Field formatter
Type PayloadFormatter
Description

defined_only
Field parameter
Type string

Message DownlinkQueueRequest

Show object example 
{
  "end_device_ids": {},
  "downlinks": [],
}

Fields:

Field end_device_ids
Type EndDeviceIdentifiers
Description

required
Field downlinks
Type repeated ApplicationDownlink
Description

max_items: 100000

Message EncodeDownlinkRequest

Show object example 
{
  "end_device_ids": {},
  "version_ids": {},
  "downlink": {},
  "formatter": "FORMATTER_NONE",
  "parameter": "",
}

Fields:

Field end_device_ids
Type EndDeviceIdentifiers
Description

required
Field version_ids
Type EndDeviceVersionIdentifiers
Field downlink
Type ApplicationDownlink
Description

required
Field formatter
Type PayloadFormatter
Description

defined_only
Field parameter
Type string

Message EndDeviceIdentifiers

Show object example 
{
  "device_id": "",
  "application_ids": {},
  "dev_eui": "",
  "join_eui": "",
  "dev_addr": "",
}

Fields:

Field device_id
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Field application_ids
Type ApplicationIdentifiers
Description

required
Field dev_eui
Type bytes
Description

The LoRaWAN DevEUI.

ignore_empty

len: 8
Field join_eui
Type bytes
Description

The LoRaWAN JoinEUI (AppEUI until LoRaWAN 1.0.3 end devices).

ignore_empty

len: 8
Field dev_addr
Type bytes
Description

The LoRaWAN DevAddr.

ignore_empty

len: 4

Message EndDeviceIdentifiersList

Show object example 
{
  "end_device_ids": [],
}

Fields:

Field end_device_ids
Type repeated EndDeviceIdentifiers
Description

Message EndDeviceVersionIdentifiers

Identifies an end device model with version information.

Show object example 
{
  "brand_id": "",
  "model_id": "",
  "hardware_version": "",
  "firmware_version": "",
  "band_id": "",
}

Fields:

Field brand_id
Type string
Description

ignore_empty

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Field model_id
Type string
Description

ignore_empty

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Field hardware_version
Type string
Description

max_len: 32
Field firmware_version
Type string
Description

max_len: 32
Field band_id
Type string
Description

max_len: 32

Message ErrorDetails

Error details that are communicated over gRPC (and HTTP) APIs. The messages (for translation) are stored as “error::”.

Show object example 
{
  "namespace": "",
  "name": "",
  "message_format": "",
  "attributes": {},
  "correlation_id": "",
  "cause": {},
  "code": 0,
  "details": [],
}

Fields:

Field namespace
Type string
Description

Namespace of the error (typically the package name in The Things Stack).
Field name
Type string
Description

Name of the error.
Field message_format
Type string
Description

The default (fallback) message format that should be used for the error. This is also used if the client does not have a translation for the error.
Field attributes
Type google.protobuf. Struct
Description

Attributes that should be filled into the message format. Any extra attributes can be displayed as error details.
Field correlation_id
Type string
Description

The correlation ID of the error can be used to correlate the error to stack traces the network may (or may not) store about recent errors.
Field cause
Type ErrorDetails
Description

The error that caused this error.
Field code
Type uint32
Description

The status code of the error.
Field details
Type repeated google.protobuf. Any
Description

The details of the error.

Message FSKDataRate

Show object example 
{
  "bit_rate": 0,
}

Fields:

Field bit_rate
Type uint32
Description

Bit rate (bps).

Message GetAsConfigurationRequest

Show object example 
{
}

Fields:

Message GatewayAntennaIdentifiers

Show object example 
{
  "gateway_ids": {},
  "antenna_index": 0,
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field antenna_index
Type uint32

Message GatewayIdentifiers

Show object example 
{
  "gateway_id": "",
  "eui": "",
}

Fields:

Field gateway_id
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Field eui
Type bytes
Description

Secondary identifier, which can only be used in specific requests.

ignore_empty

len: 8

Message GetApplicationLinkRequest

Show object example 
{
  "application_ids": {},
  "field_mask": {},
}

Fields:

Field application_ids
Type ApplicationIdentifiers
Description

required
Field field_mask
Type google.protobuf. FieldMask

Message KeyEnvelope

Show object example 
{
  "key": "",
  "kek_label": "",
  "encrypted_key": "",
}

Fields:

Field key
Type bytes
Description

The unencrypted AES key.

ignore_empty

len: 16
Field kek_label
Type string
Description

The label of the RFC 3394 key-encryption-key (KEK) that was used to encrypt the key.

max_len: 2048
Field encrypted_key
Type bytes
Description

max_len: 1024

Message LastBatteryPercentage

Show object example 
{
  "f_cnt": 0,
  "value": null,
  "received_at": "0001-01-01T00:00:00Z",
}

Fields:

Field f_cnt
Type uint32
Description

Frame counter value of last uplink containing DevStatusAns.
Field value
Type google.protobuf. FloatValue
Description

The battery percentage of the end device. The value is defined in the [0, 100] interval.

gte: 0

lte: 100
Field received_at
Type google.protobuf. Timestamp
Description

Time when last DevStatus MAC command was received.

Message Location

Show object example 
{
  "latitude": 0,
  "longitude": 0,
  "altitude": 0,
  "accuracy": 0,
  "source": "SOURCE_UNKNOWN",
}

Fields:

Field latitude
Type double
Description

The North–South position (degrees; -90 to +90), where 0 is the equator, North pole is positive, South pole is negative.

gte: -90

lte: 90
Field longitude
Type double
Description

The East-West position (degrees; -180 to +180), where 0 is the Prime Meridian (Greenwich), East is positive , West is negative.

gte: -180

lte: 180
Field altitude
Type int32
Description

The altitude (meters), where 0 is the mean sea level.
Field accuracy
Type int32
Description

The accuracy of the location (meters).
Field source
Type LocationSource
Description

Source of the location information.

defined_only

Message LoRaDataRate

Show object example 
{
  "bandwidth": 0,
  "spreading_factor": 0,
  "coding_rate": "",
}

Fields:

Field bandwidth
Type uint32
Description

Bandwidth (Hz).
Field spreading_factor
Type uint32
Field coding_rate
Type string

Message LRFHSSDataRate

Show object example 
{
  "modulation_type": 0,
  "operating_channel_width": 0,
  "coding_rate": "",
}

Fields:

Field modulation_type
Type uint32
Field operating_channel_width
Type uint32
Description

Operating Channel Width (Hz).
Field coding_rate
Type string

Message MessagePayloadFormatters

Show object example 
{
  "up_formatter": "FORMATTER_NONE",
  "up_formatter_parameter": "",
  "down_formatter": "FORMATTER_NONE",
  "down_formatter_parameter": "",
}

Fields:

Field up_formatter
Type PayloadFormatter
Description

Payload formatter for uplink messages, must be set together with its parameter.

defined_only
Field up_formatter_parameter
Type string
Description

Parameter for the up_formatter, must be set together. The API enforces a maximum length of 16KB, but the size may be restricted further by deployment configuration.

max_len: 40960
Field down_formatter
Type PayloadFormatter
Description

Payload formatter for downlink messages, must be set together with its parameter.

defined_only
Field down_formatter_parameter
Type string
Description

Parameter for the down_formatter, must be set together. The API enforces a maximum length of 16KB, but the size may be restricted further by deployment configuration.

max_len: 40960

Message NetworkIdentifiers

Identifies a Network Server.

Show object example 
{
  "net_id": "",
  "ns_id": "",
  "tenant_id": "",
  "cluster_id": "",
  "cluster_address": "",
  "tenant_address": "",
}

Fields:

Field net_id
Type bytes
Description

LoRa Alliance NetID.

ignore_empty

len: 3
Field ns_id
Type bytes
Description

LoRaWAN NSID (EUI-64) that uniquely identifies the Network Server instance.

ignore_empty

len: 8
Field tenant_id
Type string
Description

Optional tenant identifier for multi-tenant deployments.

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$|^$
Field cluster_id
Type string
Description

Cluster identifier of the Network Server.

max_len: 64
Field cluster_address
Type string
Description

Cluster address of the Network Server.

max_len: 256
Field tenant_address
Type string
Description

Optional tenant address for multi-tenant deployments.

max_len: 256

Message PacketBrokerMetadata

Show object example 
{
  "message_id": "",
  "forwarder_net_id": "",
  "forwarder_tenant_id": "",
  "forwarder_cluster_id": "",
  "forwarder_gateway_eui": "",
  "forwarder_gateway_id": null,
  "home_network_net_id": "",
  "home_network_tenant_id": "",
  "home_network_cluster_id": "",
  "hops": [],
}

Fields:

Field message_id
Type string
Description

Message identifier generated by Packet Broker Router.
Field forwarder_net_id
Type bytes
Description

LoRa Alliance NetID of the Packet Broker Forwarder Member.

ignore_empty

len: 3
Field forwarder_tenant_id
Type string
Description

Tenant ID managed by the Packet Broker Forwarder Member.
Field forwarder_cluster_id
Type string
Description

Forwarder Cluster ID of the Packet Broker Forwarder.
Field forwarder_gateway_eui
Type bytes
Description

Forwarder gateway EUI.

ignore_empty

len: 8
Field forwarder_gateway_id
Type google.protobuf. StringValue
Description

Forwarder gateway ID.
Field home_network_net_id
Type bytes
Description

LoRa Alliance NetID of the Packet Broker Home Network Member.

ignore_empty

len: 3
Field home_network_tenant_id
Type string
Description

Tenant ID managed by the Packet Broker Home Network Member. This value is empty if it cannot be determined by the Packet Broker Router.
Field home_network_cluster_id
Type string
Description

Home Network Cluster ID of the Packet Broker Home Network.
Field hops
Type repeated PacketBrokerRouteHop
Description

Hops that the message passed. Each Packet Broker Router service appends an entry.

Message PacketBrokerRouteHop

Show object example 
{
  "received_at": "0001-01-01T00:00:00Z",
  "sender_name": "",
  "sender_address": "",
  "receiver_name": "",
  "receiver_agent": "",
}

Fields:

Field received_at
Type google.protobuf. Timestamp
Description

Time when the service received the message.
Field sender_name
Type string
Description

Sender of the message, typically the authorized client identifier.
Field sender_address
Type string
Description

Sender IP address or host name.
Field receiver_name
Type string
Description

Receiver of the message.
Field receiver_agent
Type string
Description

Receiver agent.

Message RelayMetadata

Show object example 
{
  "device_id": "",
  "wor_channel": "RELAY_WOR_CHANNEL_DEFAULT",
}

Fields:

Field device_id
Type string
Description

End device identifiers of the relay.

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Field wor_channel
Type RelayWORChannel
Description

Wake on radio channel.

defined_only

Message RxMetadata

Contains metadata for a received message. Each antenna that receives a message corresponds to one RxMetadata.

Show object example 
{
  "gateway_ids": {},
  "packet_broker": {},
  "relay": {},
  "antenna_index": 0,
  "time": "0001-01-01T00:00:00Z",
  "timestamp": 0,
  "fine_timestamp": 0,
  "encrypted_fine_timestamp": "",
  "encrypted_fine_timestamp_key_id": "",
  "rssi": 0,
  "signal_rssi": null,
  "channel_rssi": 0,
  "rssi_standard_deviation": 0,
  "snr": 0,
  "frequency_offset": 0,
  "location": {},
  "downlink_path_constraint": "DOWNLINK_PATH_CONSTRAINT_NONE",
  "uplink_token": "",
  "channel_index": 0,
  "hopping_width": 0,
  "frequency_drift": 0,
  "gps_time": "0001-01-01T00:00:00Z",
  "received_at": "0001-01-01T00:00:00Z",
  "advanced": {},
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field packet_broker
Type PacketBrokerMetadata
Field relay
Type RelayMetadata
Field antenna_index
Type uint32
Field time
Type google.protobuf. Timestamp
Description

Timestamp at the end of the transmission, provided by the gateway. The accuracy is undefined.
Field timestamp
Type uint32
Description

Gateway concentrator timestamp when the Rx finished (microseconds).
Field fine_timestamp
Type uint64
Description

Gateway’s internal fine timestamp when the Rx finished (nanoseconds).
Field encrypted_fine_timestamp
Type bytes
Description

Encrypted gateway’s internal fine timestamp when the Rx finished (nanoseconds).
Field encrypted_fine_timestamp_key_id
Type string
Field rssi
Type float
Description

Received signal strength indicator (dBm). This value equals channel_rssi.
Field signal_rssi
Type google.protobuf. FloatValue
Description

Received signal strength indicator of the signal (dBm).
Field channel_rssi
Type float
Description

Received signal strength indicator of the channel (dBm).
Field rssi_standard_deviation
Type float
Description

Standard deviation of the RSSI during preamble.
Field snr
Type float
Description

Signal-to-noise ratio (dB).
Field frequency_offset
Type int64
Description

Frequency offset (Hz).
Field location
Type Location
Description

Antenna location; injected by the Gateway Server.
Field downlink_path_constraint
Type DownlinkPathConstraint
Description

Gateway downlink path constraint; injected by the Gateway Server.

defined_only
Field uplink_token
Type bytes
Description

Uplink token to be included in the Tx request in class A downlink; injected by gateway, Gateway Server or fNS.
Field channel_index
Type uint32
Description

Index of the gateway channel that received the message.

lte: 255
Field hopping_width
Type uint32
Description

Hopping width; a number describing the number of steps of the LR-FHSS grid.
Field frequency_drift
Type int32
Description

Frequency drift in Hz between start and end of an LR-FHSS packet (signed).
Field gps_time
Type google.protobuf. Timestamp
Description

Timestamp at the end of the transmission, provided by the gateway. Guaranteed to be based on a GPS PPS signal, with an accuracy of 1 millisecond.
Field received_at
Type google.protobuf. Timestamp
Description

Timestamp at which the Gateway Server has received the message.
Field advanced
Type google.protobuf. Struct
Description

Advanced metadata fields

  • can be used for advanced information or experimental features that are not yet formally defined in the API
  • field names are written in snake_case

Message SessionKeyRequest

Show object example 
{
  "session_key_id": "",
  "dev_eui": "",
  "join_eui": "",
}

Fields:

Field session_key_id
Type bytes
Description

Join Server issued identifier for the session keys.

max_len: 2048
Field dev_eui
Type bytes
Description

LoRaWAN DevEUI.

ignore_empty

len: 8
Field join_eui
Type bytes
Description

The LoRaWAN JoinEUI (AppEUI until LoRaWAN 1.0.3 end devices).

ignore_empty

len: 8

Message SetApplicationLinkRequest

Show object example 
{
  "application_ids": {},
  "link": {},
  "field_mask": {},
}

Fields:

Field application_ids
Type ApplicationIdentifiers
Description

required
Field link
Type ApplicationLink
Description

required
Field field_mask
Type google.protobuf. FieldMask

Message TxSettings

TxSettings contains the settings for a transmission. This message is used on both uplink and downlink. On downlink, this is a scheduled transmission.

Show object example 
{
  "data_rate": {},
  "frequency": 0,
  "enable_crc": false,
  "timestamp": 0,
  "time": "0001-01-01T00:00:00Z",
  "downlink": {},
  "concentrator_timestamp": 0,
}

Fields:

Field data_rate
Type DataRate
Description

Data rate.

required
Field frequency
Type uint64
Description

Frequency (Hz).

gte: 100000
Field enable_crc
Type bool
Description

Send a CRC in the packet; only on uplink; on downlink, CRC should not be enabled.
Field timestamp
Type uint32
Description

Timestamp of the gateway concentrator when the uplink message was received, or when the downlink message should be transmitted (microseconds). On downlink, set timestamp to 0 and time to null to use immediate scheduling.
Field time
Type google.protobuf. Timestamp
Description

Time of the gateway when the uplink message was received, or when the downlink message should be transmitted. For downlink, this requires the gateway to have GPS time synchronization.
Field downlink
Type TxSettings.Downlink
Description

Transmission settings for downlink.
Field concentrator_timestamp
Type int64
Description

Concentrator timestamp for the downlink as calculated by the Gateway Server scheduler. This value takes into account necessary offsets such as the RTT (Round Trip Time) and TOA (Time Of Arrival). This field is set and used only by the Gateway Server.

Transmission settings for downlink.

Show object example 
{
  "antenna_index": 0,
  "tx_power": 0,
  "invert_polarization": false,
}

Fields:

Field antenna_index
Type uint32
Description

Index of the antenna on which the uplink was received and/or downlink must be sent.
Field tx_power
Type float
Description

Transmission power (dBm). Only on downlink.
Field invert_polarization
Type bool
Description

Invert LoRa polarization; false for LoRaWAN uplink, true for downlink.

Enums

Enum DownlinkPathConstraint

Name Value Description
DOWNLINK_PATH_CONSTRAINT_NONE 0 Indicates that the gateway can be selected for downlink without constraints by the Network Server.
DOWNLINK_PATH_CONSTRAINT_PREFER_OTHER 1 Indicates that the gateway can be selected for downlink only if no other or better gateway can be selected.
DOWNLINK_PATH_CONSTRAINT_NEVER 2 Indicates that this gateway will never be selected for downlink, even if that results in no available downlink path.

Enum LocationSource

Name Value Description
SOURCE_UNKNOWN 0 The source of the location is not known or not set.
SOURCE_GPS 1 The location is determined by GPS.
SOURCE_REGISTRY 3 The location is set in and updated from a registry.
SOURCE_IP_GEOLOCATION 4 The location is estimated with IP geolocation.
SOURCE_WIFI_RSSI_GEOLOCATION 5 The location is estimated with WiFi RSSI geolocation.
SOURCE_BT_RSSI_GEOLOCATION 6 The location is estimated with BT/BLE RSSI geolocation.
SOURCE_LORA_RSSI_GEOLOCATION 7 The location is estimated with LoRa RSSI geolocation.
SOURCE_LORA_TDOA_GEOLOCATION 8 The location is estimated with LoRa TDOA geolocation.
SOURCE_COMBINED_GEOLOCATION 9 The location is estimated by a combination of geolocation sources.

Enum PayloadFormatter

Name Value Description
FORMATTER_NONE 0 No payload formatter to work with raw payload only.
FORMATTER_REPOSITORY 1 Use payload formatter for the end device type from a repository.
FORMATTER_GRPC_SERVICE 2 gRPC service payload formatter. The parameter is the host:port of the service.
FORMATTER_JAVASCRIPT 3 Custom payload formatter that executes Javascript code. The parameter is a JavaScript filename.
FORMATTER_CAYENNELPP 4 CayenneLPP payload formatter.

Enum RelayWORChannel

Name Value Description
RELAY_WOR_CHANNEL_DEFAULT 0
RELAY_WOR_CHANNEL_SECONDARY 1

Enum TxSchedulePriority

Name Value Description
LOWEST 0
LOW 1
BELOW_NORMAL 2
NORMAL 3
ABOVE_NORMAL 4
HIGH 5
HIGHEST 6
← Application Pub/Sub APIs Application Webhook APIs →