HTTP Requests¶

Request Format¶

Requests are HTTP GET/PUT/POST/DELETE requests and share the following properties across endpoints.

GET /api/v1/<CATEGORY>/{ENTITY/}*<OPERATION>¶

PUT /api/v1/<CATEGORY>/{ENTITY/}*<OPERATION>¶

POST /api/v1/<CATEGORY>/{ENTITY/}*<OPERATION>¶

DELETE /api/v1/<CATEGORY>/{ENTITY/}*<OPERATION>¶

All requests target a URI of the specified format. All request headers must carry a valid access token. Access tokens are associated with specific capabilities that allow for fine-grained access control (see Token Management API). Requests may address an entity by a URI element in the URI path. Requests include request parameters in the URI or in the body of the request, in JSON format.

Request Headers

Authorization – Required. Access token

Request Body:

Most requests carry a request body with a JSON object. The format of the request body depends on the request. All requests share the expected format for certain fields:

DEVEUI: EUI-64, expected in dash-separated hexadecimal notation, e.g. 00-02-77-AA-BB-01-0510
TOKEN: string

Response:

Status Codes

200 OK – OK
400 Bad Request – Input validation error
401 Unauthorized – Authentication failed
429 Too Many Requests – Rate limit exceeded

Response Headers

Content-Type – ‘application/json’

Response JSON:

Response data is returned in JSON format and adheres to the following format (Base Response Format):

{
   "result":   OBJECT,         // Optional. Result of operation
   "errors":   [ STRING, .. ]  // Optional. List of error messages
   "warnings": [ STRING, .. ]  // Optional. List of warning messages
   "infos":    [ STRING, .. ]  // Optional. List of information messages
}

Results are stored in the result field where NULL might be a valid result, depending on the invocation. Errors occurring during the invocation are stored in the errors field.

When parsing the JSON response, clients should ignore extra fields which are not listed in this documentation, also for future backward compatibility.

If requests take a set of device EUIs, the operation might succeed or fail for a particular EUI. The result field in the response data then adheres to the following format (EUIs Response Format):

{
   DEVEUI: {
     "result":   OBJECT,         // Optional. Result of operation
     "error":    STRING          // Optional. Error message related to device.
   }
}

List of API Endpoints¶

The current list of supported API endpoints and required token capabilities (see Token Management API) is listed here for each API category. For a flat index into all available API endpoints, go to the HTTP Routing Table.

→ Token Management API endpoints

Method / API Endpoint	Description	Required Token Capabilities
POST /api/v1/token/add	Create new API token	tok:mgmt
GET /api/v1/token/list	List existing API token	tok:mgmt
GET /api/v1/token/(string: TOKEN)	Get info for token	tok:rd
PUT /api/v1/token/(string: TOKEN)	Rename or renew single token	tok:rd
DELETE /api/v1/token/(string: TOKEN)	Delete Token	tok:mgmt

→ Modem and Geolocation API endpoints

Method / API Endpoint	Description	Required Token Capabilities
POST /api/v1/device/add	Add device	dev:mgmt
POST /api/v1/device/remove	Remove device	dev:mgmt
GET /api/v1/device/count	Get Device count	dev:rd
POST /api/v1/device/list	List registered device EUIs	dev:rd
POST /api/v1/device/info	Get device state for list of device EUIs	dev:rd
POST /api/v1/device/list_infos	List device states	dev:rd
POST /api/v1/device/set	Set device specific configuration	dev:rd
POST /api/v1/device/clear	Clear device state on the server	dev:up
POST /api/v1/uplink/send	Submit uplinks from devices	dev:up
POST /api/v1/device/send	Submit uplink from device	dev:rd
POST /api/v1/requests/add	Add modem request to request queue	dev:dn
POST /api/v1/requests/set	Replace request queue with single modem request	dev:dn
POST /api/v1/requests/clear	Clear modem request queue for devices	dev:dn
POST /api/v1/uploads/fetch	Get the file upload history for devices	dev:rd
GET /api/v1/devowner/config	Get owner defaults for device specific configuration	dev:rd
PUT /api/v1/devowner/config	Change owner defaults for device specific configuration	dev:rd

→ Common APIs endpoints

Method / API Endpoint	Description	Required Token Capabilities
GET /api/v1/almanac/full	Get LoRa Edge™ full almanac image	gnss:rd

→ Geolocation API Primitives endpoints

Method / API Endpoint	Description	Required Token Capabilities
POST /api/v1/solve/rssi	Invoke LoRa RSSI Solver	dev:rd
POST /api/v1/solve/tdoa	Invoke LoRa TDOA Solver	dev:rd
POST /api/v1/solve/rssiMultiframe	Invoke LoRa RSSI Multiframe Solver	dev:rd
POST /api/v1/solve/tdoaMultiframe	Invoke LoRa TDOA Multiframe Solver	dev:rd
POST /api/v1/solve/loraWifi	Invoke combined LoRa TDOA/RSSI and Wi-Fi Solver	dev:rd
POST /api/v1/solve/singleframe	Invoke combined LoRa TDOA/RSSI Solver	dev:rd
POST /api/v1/solve/multiframe	Invoke combined LoRa TDOA/RSSI Multiframe Solver	dev:rd
POST /api/v1/solve/singleframes	Invoke combined LoRa TDOA/RSSI Bulk Solver	dev:rd
POST /api/v1/solve/multiframes	Invoke combined LoRa TDOA/RSSI Multiframe Bulk Solver	dev:rd
POST /api/v1/solve/gnss_lora_edge_singleframe	Invoke LoRa Edge single-frame GNSS solver	gnss:rd
POST /api/v1/solve/gnss_lora_edge_multiframe	Invoke LoRa Edge Multi-Frame GNSS Solver	gnss:rd

→ Legacy endpoints:

The legacy ‘LoRaCloud Geolocation Service’ endpoints are DEPRECATED and superseded by their /api/v1/ counterparts (follow links).

POST /api/v2/rssi
POST /api/v2/tdoa
POST /api/v2/rssiMultiframe
POST /api/v2/tdoaMultiframe
POST /api/v2/loraWifi
POST /api/v3/solve/singleframe
POST /api/v3/solve/singleframe
POST /api/v3/solve/singleframes
POST /api/v3/solve/multiframes
POST /api/v3/solve/gnss_lr1110_singleframe
POST /api/v3/solve/gnss_lr1110_multiframe
GET /api/v3/almanac/full

Note

These legacy endpoints exist for the convenience of former ‘LoRaCloud Geolocation Service’ users. The endpoints are superseded by their /api/v1/ counterparts and will be phased out. Existing users are encouraged to move to the /api/v1/ geolocation solver endpoints. The only change is the name of the HTTP authentiation header from Ocp-Apim-Subscription-Key: <TOKEN> to Authorization: <TOKEN>. For more information, consult the Migration Guide.