swagger: '2.0'
info:
title: The Things Stack — Application Server AppAs ApplicationUpStorage 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: ApplicationUpStorage
paths:
/as/applications/{application_ids.application_id}/packages/storage/{type}:
get:
summary: Returns a stream of application messages that have been stored in the database.
operationId: ApplicationUpStorage_GetStoredApplicationUp2
responses:
'200':
description: A successful response.(streaming responses)
schema:
type: object
properties:
result:
$ref: '#/definitions/v3ApplicationUp'
error:
$ref: '#/definitions/googlerpcStatus'
title: Stream result of v3ApplicationUp
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: application_ids.application_id
in: path
required: true
type: string
- name: type
description: Query upstream messages of a specific type. If not set, then all upstream messages are returned.
in: path
required: true
type: string
- name: end_device_ids.device_id
in: query
required: false
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: limit
description: Limit number of results.
in: query
required: false
type: integer
format: int64
- name: after
description: Query upstream messages after this timestamp only. Cannot be used in conjunction with last.
in: query
required: false
type: string
format: date-time
- name: before
description: Query upstream messages before this timestamp only. Cannot be used in conjunction with last.
in: query
required: false
type: string
format: date-time
- name: f_port
description: Query uplinks on a specific FPort only.
in: query
required: false
type: integer
format: int64
- name: order
description: Order results.
in: query
required: false
type: string
- name: field_mask
description: 'The names of the upstream message fields that should be returned. See the API reference
for allowed field names for each type of upstream message.'
in: query
required: false
type: string
- name: last
description: Query upstream messages that have arrived in the last minutes or hours. Cannot be used in conjunction with after and before.
in: query
required: false
type: string
- name: continuation_token
description: The continuation token, which is used to retrieve the next page. If provided, other fields are ignored.
in: query
required: false
type: string
tags:
- ApplicationUpStorage
/as/applications/{application_ids.application_id}/packages/storage/{type}/count:
get:
summary: Returns how many application messages have been stored in the database for an application or end device.
operationId: ApplicationUpStorage_GetStoredApplicationUpCount2
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v3GetStoredApplicationUpCountResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: application_ids.application_id
in: path
required: true
type: string
- name: type
description: Count upstream messages of a specific type. If not set, then all upstream messages are returned.
in: path
required: true
type: string
- name: end_device_ids.device_id
in: query
required: false
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: after
description: Count upstream messages after this timestamp only. Cannot be used in conjunction with last.
in: query
required: false
type: string
format: date-time
- name: before
description: Count upstream messages before this timestamp only. Cannot be used in conjunction with last.
in: query
required: false
type: string
format: date-time
- name: f_port
description: Count uplinks on a specific FPort only.
in: query
required: false
type: integer
format: int64
- name: last
description: Count upstream messages that have arrived in the last minutes or hours. Cannot be used in conjunction with after and before.
in: query
required: false
type: string
tags:
- ApplicationUpStorage
? /as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/packages/storage/{type}
: get:
summary: Returns a stream of application messages that have been stored in the database.
operationId: ApplicationUpStorage_GetStoredApplicationUp
responses:
'200':
description: A successful response.(streaming responses)
schema:
type: object
properties:
result:
$ref: '#/definitions/v3ApplicationUp'
error:
$ref: '#/definitions/googlerpcStatus'
title: Stream result of v3ApplicationUp
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: type
description: Query upstream messages of a specific type. If not set, then all upstream messages are returned.
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: limit
description: Limit number of results.
in: query
required: false
type: integer
format: int64
- name: after
description: Query upstream messages after this timestamp only. Cannot be used in conjunction with last.
in: query
required: false
type: string
format: date-time
- name: before
description: Query upstream messages before this timestamp only. Cannot be used in conjunction with last.
in: query
required: false
type: string
format: date-time
- name: f_port
description: Query uplinks on a specific FPort only.
in: query
required: false
type: integer
format: int64
- name: order
description: Order results.
in: query
required: false
type: string
- name: field_mask
description: 'The names of the upstream message fields that should be returned. See the API reference
for allowed field names for each type of upstream message.'
in: query
required: false
type: string
- name: last
description: Query upstream messages that have arrived in the last minutes or hours. Cannot be used in conjunction with after and before.
in: query
required: false
type: string
- name: continuation_token
description: The continuation token, which is used to retrieve the next page. If provided, other fields are ignored.
in: query
required: false
type: string
tags:
- ApplicationUpStorage
? /as/applications/{end_device_ids.application_ids.application_id}/devices/{end_device_ids.device_id}/packages/storage/{type}/count
: get:
summary: Returns how many application messages have been stored in the database for an application or end device.
operationId: ApplicationUpStorage_GetStoredApplicationUpCount
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v3GetStoredApplicationUpCountResponse'
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: type
description: Count upstream messages of a specific type. If not set, then all upstream messages are returned.
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: after
description: Count upstream messages after this timestamp only. Cannot be used in conjunction with last.
in: query
required: false
type: string
format: date-time
- name: before
description: Count upstream messages before this timestamp only. Cannot be used in conjunction with last.
in: query
required: false
type: string
format: date-time
- name: f_port
description: Count uplinks on a specific FPort only.
in: query
required: false
type: integer
format: int64
- name: last
description: Count upstream messages that have arrived in the last minutes or hours. Cannot be used in conjunction with after and before.
in: query
required: false
type: string
tags:
- ApplicationUpStorage
definitions:
v3ApplicationUp:
type: object
properties:
end_device_ids:
$ref: '#/definitions/v3EndDeviceIdentifiers'
correlation_ids:
type: array
items:
type: string
received_at:
type: string
format: date-time
description: Server time when the Application Server received the message.
uplink_message:
$ref: '#/definitions/v3ApplicationUplink'
uplink_normalized:
$ref: '#/definitions/v3ApplicationUplinkNormalized'
join_accept:
$ref: '#/definitions/v3ApplicationJoinAccept'
downlink_ack:
$ref: '#/definitions/v3ApplicationDownlink'
downlink_nack:
$ref: '#/definitions/v3ApplicationDownlink'
downlink_sent:
$ref: '#/definitions/v3ApplicationDownlink'
downlink_failed:
$ref: '#/definitions/v3ApplicationDownlinkFailed'
downlink_queued:
$ref: '#/definitions/v3ApplicationDownlink'
downlink_queue_invalidated:
$ref: '#/definitions/v3ApplicationInvalidatedDownlinks'
location_solved:
$ref: '#/definitions/v3ApplicationLocation'
service_data:
$ref: '#/definitions/v3ApplicationServiceData'
simulated:
type: boolean
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.'
description: Application uplink message.
v3LoRaDataRate:
type: object
properties:
bandwidth:
type: integer
format: int64
description: Bandwidth (Hz).
spreading_factor:
type: integer
format: int64
coding_rate:
type: string
lorawanv3RxMetadata:
type: object
properties:
gateway_ids:
$ref: '#/definitions/lorawanv3GatewayIdentifiers'
packet_broker:
$ref: '#/definitions/lorawanv3PacketBrokerMetadata'
relay:
$ref: '#/definitions/lorawanv3RelayMetadata'
antenna_index:
type: integer
format: int64
time:
type: string
format: date-time
description: Timestamp at the end of the transmission, provided by the gateway. The accuracy is undefined.
timestamp:
type: integer
format: int64
description: Gateway concentrator timestamp when the Rx finished (microseconds).
fine_timestamp:
type: string
format: uint64
description: Gateway's internal fine timestamp when the Rx finished (nanoseconds).
encrypted_fine_timestamp:
type: string
format: byte
description: Encrypted gateway's internal fine timestamp when the Rx finished (nanoseconds).
encrypted_fine_timestamp_key_id:
type: string
rssi:
type: number
format: float
description: 'Received signal strength indicator (dBm).
This value equals `channel_rssi`.'
signal_rssi:
type: number
format: float
description: Received signal strength indicator of the signal (dBm).
channel_rssi:
type: number
format: float
description: Received signal strength indicator of the channel (dBm).
rssi_standard_deviation:
type: number
format: float
description: Standard deviation of the RSSI during preamble.
snr:
type: number
format: float
description: Signal-to-noise ratio (dB).
frequency_offset:
type: string
format: int64
description: Frequency offset (Hz).
location:
$ref: '#/definitions/lorawanv3Location'
description: Antenna location; injected by the Gateway Server.
downlink_path_constraint:
$ref: '#/definitions/v3DownlinkPathConstraint'
description: Gateway downlink path constraint; injected by the Gateway Server.
uplink_token:
type: string
format: byte
description: Uplink token to be included in the Tx request in class A downlink; injected by gateway, Gateway Server or fNS.
channel_index:
type: integer
format: int64
description: Index of the gateway channel that received the message.
hopping_width:
type: integer
format: int64
description: Hopping width; a number describing the number of steps of the LR-FHSS grid.
frequency_drift:
type: integer
format: int32
description: Frequency drift in Hz between start and end of an LR-FHSS packet (signed).
gps_time:
type: string
format: date-time
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.'
received_at:
type: string
format: date-time
description: Timestamp at which the Gateway Server has received the message.
advanced:
type: object
title: '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'
description: 'Contains metadata for a received message. Each antenna that receives
a message corresponds to one RxMetadata.'
v3ApplicationDownlink:
type: object
properties:
session_key_id:
type: string
format: byte
description: Join Server issued identifier for the session keys used by this downlink.
f_port:
type: integer
format: int64
f_cnt:
type: integer
format: int64
frm_payload:
type: string
format: byte
description: 'The frame payload of the downlink message.
The payload is encrypted if the skip_payload_crypto field of the EndDevice
is true.'
decoded_payload:
type: object
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.'
decoded_payload_warnings:
type: array
items:
type: string
description: Warnings generated by the message processor while encoding frm_payload (scheduling downlink) or decoding the frm_payload (reading downlink).
confirmed:
type: boolean
class_b_c:
$ref: '#/definitions/ApplicationDownlinkClassBC'
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.'
priority:
$ref: '#/definitions/v3TxSchedulePriority'
description: Priority for scheduling the downlink message.
correlation_ids:
type: array
items:
type: string
confirmed_retry:
$ref: '#/definitions/ApplicationDownlinkConfirmedRetry'
locations:
type: object
additionalProperties:
$ref: '#/definitions/lorawanv3Location'
description: End device location metadata, set by the Application Server while handling the message.
version_ids:
$ref: '#/definitions/v3EndDeviceVersionIdentifiers'
description: End device version identifiers, set by the Application Server while handling the message.
network_ids:
$ref: '#/definitions/v3NetworkIdentifiers'
description: Network identifiers, set by the Network Server that handles the message.
attributes:
type: object
additionalProperties:
type: string
description: Attributes for devices, set by the Application Server while handling the message.
v3ApplicationUplink:
type: object
properties:
session_key_id:
type: string
format: byte
description: Join Server issued identifier for the session keys used by this uplink.
f_port:
type: integer
format: int64
description: LoRaWAN FPort of the uplink message.
f_cnt:
type: integer
format: int64
description: LoRaWAN FCntUp of the uplink message.
frm_payload:
type: string
format: byte
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.'
decoded_payload:
type: object
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).'
decoded_payload_warnings:
type: array
items:
type: string
description: Warnings generated by the message processor while decoding the frm_payload.
normalized_payload:
type: array
items:
type: object
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.'
normalized_payload_warnings:
type: array
items:
type: string
description: Warnings generated by the message processor while normalizing the decoded payload.
rx_metadata:
type: array
items:
type: object
$ref: '#/definitions/lorawanv3RxMetadata'
description: A list of metadata for each antenna of each gateway that received this message.
settings:
$ref: '#/definitions/lorawanv3TxSettings'
description: Transmission settings used by the end device.
received_at:
type: string
format: date-time
description: Server time when the Network Server received the message.
app_s_key:
$ref: '#/definitions/v3KeyEnvelope'
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.'
last_a_f_cnt_down:
type: integer
format: int64
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.'
confirmed:
type: boolean
description: Indicates whether the end device used confirmed data uplink.
consumed_airtime:
type: string
description: Consumed airtime for the transmission of the uplink message. Calculated by Network Server using the raw payload size and the transmission settings.
packet_error_rate:
type: number
format: 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.'
locations:
type: object
additionalProperties:
$ref: '#/definitions/lorawanv3Location'
description: End device location metadata, set by the Application Server while handling the message.
version_ids:
$ref: '#/definitions/v3EndDeviceVersionIdentifiers'
description: End device version identifiers, set by the Application Server while handling the message.
network_ids:
$ref: '#/definitions/v3NetworkIdentifiers'
description: Network identifiers, set by the Network Server that handles the message.
last_battery_percentage:
$ref: '#/definitions/v3LastBatteryPercentage'
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.'
attributes:
type: object
additionalProperties:
type: string
description: Attributes for devices, set by the Application Server while handling the message.
v3TxSchedulePriority:
type: string
enum:
- LOWEST
- LOW
- BELOW_NORMAL
- NORMAL
- ABOVE_NORMAL
- HIGH
- HIGHEST
default: LOWEST
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."
v3ApplicationLocation:
type: object
properties:
service:
type: string
location:
$ref: '#/definitions/lorawanv3Location'
attributes:
type: object
additionalProperties:
type: string
v3ClassBCGatewayIdentifiers:
type: object
properties:
gateway_ids:
$ref: '#/definitions/lorawanv3GatewayIdentifiers'
antenna_index:
type: integer
format: int64
group_index:
type: integer
format: int64
lorawanv3GatewayIdentifiers:
type: object
properties:
gateway_id:
type: string
eui:
type: string
format: string
example: 70B3D57ED000ABCD
description: Secondary identifier, which can only be used in specific requests.
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.
v3LastBatteryPercentage:
type: object
properties:
f_cnt:
type: integer
format: int64
description: Frame counter value of last uplink containing DevStatusAns.
value:
type: number
format: float
description: 'The battery percentage of the end device.
The value is defined in the [0, 100] interval.'
received_at:
type: string
format: date-time
description: Time when last DevStatus MAC command was received.
v3EndDeviceIdentifiers:
type: object
properties:
device_id:
type: string
application_ids:
$ref: '#/definitions/v3ApplicationIdentifiers'
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.
v3GetStoredApplicationUpCountResponse:
type: object
properties:
count:
type: object
additionalProperties:
type: integer
format: int64
description: Number of stored messages by end device ID.
ApplicationDownlinkClassBC:
type: object
properties:
gateways:
type: array
items:
type: object
$ref: '#/definitions/v3ClassBCGatewayIdentifiers'
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.'
absolute_time:
type: string
format: date-time
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.'
lorawanv3Location:
type: object
properties:
latitude:
type: number
format: double
description: The North–South position (degrees; -90 to +90), where 0 is the equator, North pole is positive, South pole is negative.
longitude:
type: number
format: double
description: The East-West position (degrees; -180 to +180), where 0 is the Prime Meridian (Greenwich), East is positive , West is negative.
altitude:
type: integer
format: int32
description: The altitude (meters), where 0 is the mean sea level.
accuracy:
type: integer
format: int32
description: The accuracy of the location (meters).
source:
$ref: '#/definitions/v3LocationSource'
description: Source of the location information.
v3KeyEnvelope:
type: object
properties:
key:
type: string
format: string
example: 0123456789ABCDEF0123456789ABCDEF
description: The unencrypted AES key.
kek_label:
type: string
description: The label of the RFC 3394 key-encryption-key (KEK) that was used to encrypt the key.
encrypted_key:
type: string
format: byte
v3PacketBrokerRouteHop:
type: object
properties:
received_at:
type: string
format: date-time
description: Time when the service received the message.
sender_name:
type: string
description: Sender of the message, typically the authorized client identifier.
sender_address:
type: string
description: Sender IP address or host name.
receiver_name:
type: string
description: Receiver of the message.
receiver_agent:
type: string
description: Receiver agent.
v3DataRate:
type: object
properties:
lora:
$ref: '#/definitions/v3LoRaDataRate'
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/the-things-network/refs/heads/main/openapi/the-things-network-applicationupstorage-api-openapi.yml