nRF Cloud CoAP API endpoints

This document describes how to interact with nRF Cloud services using the CoAP protocol.

The CoAP API is available through coaps://coap.nrfcloud.com.

The CLI tool for CoAP communication used in this document is available from the CoAP Java Library repository.

Support

DevZone is Nordic Semiconductor's official tech support site and community. Get help from a dedicated tech support team and more than 25,000 other community members.

If you encounter unexpected behavior or errors, check the current status of nRF Cloud.

Security

nRF Cloud CoAP communication is secured by DTLS. The client must authenticate itself after a DTLS session is established by sending an authentication request (either POST /p/auth-jwt, POST /auth/jwt or POST /auth/jwt-id).

After the client is authenticated, the corresponding DTLS session remains valid for the number of seconds provided in the Max-Age option of the response (usually 30 days).

Each time the client establishes a new DTLS session, it must authenticate itself again. Sending a request without authentication will result in a 401 Unauthorized response.

Provisioning Services

This section describes endpoints related to Provisioning Services.

POST /p/auth-jwt

Authenticates the client using an Identity JWT. The JWT is passed in the payload of the request.

note

This endpoint provides authentication only for provisioning endpoints. To access the Core Services API, the client must authenticate using the POST /auth/jwt endpoint.

Parameters:

• mver: (optional) modem version, for example: mfw_nrf91x1_2.0.1
• cver: (optional) client version, for example: v3.6.99-ncs2-339-gb53d93cd77e2
• dver: (optional) CDDL version, for example: 1

Response codes:

Response code	Description
2.01 Created	Authenticated successfully. The established authenticated session is valid for the number of seconds provided in the Max-Age option of the response.
4.03 Forbidden	Authentication failed
5.00 Internal Server Error	Server error, retry later (use exponential retry mechanism)
5.03 Service Unavailable	Service is temporarily unavailable (use exponential retry mechanism)

GET /p/cmd

Fetch provisioning commands. See nRF Cloud Provisioning Service Overview for details.

Parameters:

• rxMaxSize (Optional): Integer of maximum response size in bytes
• txMaxSize (Optional): Integer of maximum device response content size in bytes

Response codes:

Response code	Description
2.05 Content	Returns list of commands to execute on a client device.
4.00 Bad request	The request was invalid: incorrect parameters or response couldn't fit into the requested buffer size
5.00 Internal Server Error	Server error, retry later (use exponential retry mechanism)

POST /p/rsp

Send result of executed commands. See nRF Cloud Provisioning Service Overview for details.

Response codes:

Response code	Description
2.04 Changed	Success
4.00 Bad request	Something was wrong in a request, for example malformed content
5.00 Internal Server Error	Server error, retry later (use exponential retry mechanism)

Core Services

Some of the nRF Cloud Core API services are also available through the CoAP API.

POST /auth/jwt

Authenticates the client using an nRF Cloud API JWT. The JWT is passed in the payload of the request.

note

After authenticating using this endpoint, only Core Services endpoints are available. To access the Provisioning API, the client must authenticate using the POST /p/auth-jwt endpoint.

Parameters:

• mver: (optional) modem version
• cver: (optional) client version

Response codes:

Response code	Description
2.01 Created	Authenticated successfully. The established authenticated session is valid for the number of seconds provided in the Max-Age option of the response.
4.03 Forbidden	Authentication failed
5.00 Internal Server Error	Server error, retry later (use exponential retry mechanism)
5.03 Service Unavailable	Service is temporarily unavailable (use exponential retry mechanism)

POST /auth/jwt-id

Authenticates the client using an Identity JWT. The JWT is passed in the payload of the request.

note

After authenticating using this endpoint only Core Services endpoints are available. To access Provisioning Services API, the client must authenticate using the POST /p/auth-jwt endpoint.

Parameters:

• mver: (optional) modem version
• cver: (optional) client version

Response codes:

Response code	Description
2.01 Created	Authenticated successfully. The established authenticated session is valid for the number of seconds provided in the Max-Age option of the response.
4.03 Forbidden	Authentication failed
5.00 Internal Server Error	Server error, retry later (use exponential retry mechanism)
5.03 Service Unavailable	Service is temporarily unavailable (use exponential retry mechanism)

GET /loc/agps

Provides assistance data to the device. Enables a faster time-to-first-fix (TTFF) for the GPS modem. Returns the modem parameters for the nRF91 GPS modem in a chunk.

See the nRF Cloud REST API documentation for details.

Example:

coap send GET "coaps://coap.nrfcloud.com:5684/loc/agps?types=2" > agps.bin

FETCH /loc/agps

Similar to GET /loc/agps but with parameters passed as a CBOR-encoded request payload.

See the nRF Cloud REST API documentation for details.

Example:

coap send FETCH -x -c 60 "coaps://coap.nrfcloud.com:5684/loc/agps" "$(<cddl/agps_sample1.cborhex)" > agps.bin

FETCH /loc/ground-fix

Gets the latitude, longitude, and uncertainty values for the LTE cell(s) or Wi-Fi access points passed. Wi-Fi will be prioritized and fall back to LTE if unavailable. At least two access points are required.

See the nRF Cloud REST API documentation for details.

Examples:

coap send -c 50 FETCH "coaps://coap.nrfcloud.com/loc/ground-fix?hiConf=true" '{"lte":[{"mcc":244,"mnc":12,"tac":12001,"eci":186369}]}'`

coap send -x -a 60 -c 60 FETCH "coaps://coap.nrfcloud.com/loc/ground-fix" "bf1381bf0618f4070c081a0002d80109192ee1ffff" > ground-fix.cbor

GET /loc/pgps

Generates GPS predictions for multiple days. The predictions are used by the nRF91 GPS modem to enable a faster time-to-first-fix (TTFF) and provide offline navigation when out of range of an LTE cell.

See the nRF Cloud REST API documentation for details.

FETCH /loc/pgps

Similar to GET /loc/pgps, but with parameters passed as a CBOR-encoded request payload.

See the nRF Cloud REST API documentation for details.

GET /loc/agnss

Provides assistance data to the device. Enables a faster time-to-first-fix (TTFF) for the GNSS modem. Returns the modem parameters for the nRF GNSS modem in a chunk. The chunk size is determined by the request Range header.

See the nRF Cloud REST API documentation for details.

Parameters are passed as query parameters in the URI.

FETCH /loc/agnss

Similar to GET /loc/agnss, but with parameters passed as a CBOR-encoded request payload.

GET /fota/exec/current

Fetches the pending (QUEUED or IN_PROGRESS) job execution with the earliest createdAt date. This allows consistent FIFO (First In First Out) processing of incoming executions.

See the nRF Cloud REST API documentation for details.

PATCH /fota/exec/{job-id}

Updates the status of the job execution with the specified job ID.

See the nRF Cloud REST API documentation for details.

Example:

coap send -c 50 PATCH "coaps://coap.nrfcloud.com/fota/exec/9140bd5d-911c-496a-9393-4acfbdb6596c" '{"status":"QUEUED"}'

POST /msg/{topic_name}

Sends a message to the {topic_name} topic. The payload is expected to be in JSON format. If the payload is CBOR encoded, it is converted to JSON.

See the nRF Cloud REST API documentation for details.

Examples:

coap send -c 50 POST "coaps://coap.nrfcloud.com/msg/142894b4-6992-4ec2-b9a4-7db749cadcdb" '{"appId":"TEMP","messageType":"DATA","data":"-12.3"}'

coap send -x -c 60 POST "coaps://coap.nrfcloud.com/msg/142894b4-6992-4ec2-b9a4-7db749cadcdb" "a2016474656d7002652d31322e33"

POST /msg/d2c

Sends a message to the default device-to-cloud topic d/{deviceId}/d2c. The payload is expected to be in JSON format. If the payload is CBOR encoded, it is converted to JSON.

See the nRF Cloud REST API documentation for details.

POST /msg/d2c/bulk

Sends a message to the default device-to-cloud topic d/{deviceId}/d2c/bulk. The payload is expected to be in JSON format. If the payload is CBOR encoded, it is converted to JSON.

See the nRF Cloud REST API documentation for details.

POST /msg/d2c/bin

Sends a message to the default device-to-cloud topic d/{deviceId}/d2c/bin.

See the nRF Cloud REST API documentation for details.

POST /msg/d2c/raw

Sends a raw binary message to the topic d/{deviceId}/d2c/raw.

See the nRF Cloud REST API documentation for details.

Example:

coap send -x POST "coaps://coap.nrfcloud.com/msg/d2c/raw" "ffaa00bb"

PATCH /state

Alias for PATCH /state/reported

PATCH /state/reported

Updates the reported part of the device shadow with the object specified in the payload. If the payload is CBOR encoded, it is converted to JSON.

See the nRF Cloud REST API documentation for details.

Examples:

coap send -c 50 PATCH "coaps://coap.nrfcloud.com/state/reported" '{"Light-2":"Off"}'

coap send -x -c 60 -a 60 PATCH "coaps://coap.nrfcloud.com/state/reported" "$(echo '{"Light-2":"Off"}' | json2cbor -x)

PATCH /state/desired

Updates the desired part of the device shadow with the object specified in the payload. If the payload is CBOR encoded, it is converted to JSON.

See the nRF Cloud REST API documentation for details.

Examples:

coap send -c 50 PATCH "coaps://coap.nrfcloud.com/state/desired" '{"Light-2":"Off"}'

coap send -x -c 60 -a 60 PATCH "coaps://coap.nrfcloud.com/state/desired" "$(echo '{"Light-2":"Off"}' | json2cbor -x)

GET /state

Retrieves the device shadow. The response is converted from JSON to CBOR if the Accept request option is application/cbor.

If the Accept option is not set, the response is returned as JSON.

See the nRF Cloud REST API documentation for details.

Query parameters:

• delta=true (default): returns only delta part of shadow
• delta=false: returns full desired part of shadow
• transform=state (default): returns shadow in jsonata transformed format, overriding the delta parameter. This fully supports the jsonata query language as used in the nRF Cloud REST API, but does not convert the response to CBOR or binary, please use the GET /state/{path} endpoint for that.

GET /state/{path}

Retrieves a specific part of the device shadow. The path specified in URI is a JSON pointer to the desired part of the shadow.

If the path is not found in the shadow, the server returns a 205 Content response with an empty payload.

The response is converted from JSON according to the Accept header of the request. If the Accept header is not set, the response is returned as JSON.

Supported conversions:

• application/cbor: response content is converted from JSON to CBOR.
• application/octet-stream: response content is decoded as a Base64 JSON string and returned as binary data.

In case of conversion failure or unsupported Accept, the server returns a 406 Not Acceptable response.

Example:

coap send GET "coaps://api.nrfcloud.com/state/desired/sensor/switch"

GET /proxy

Download files over COAP instead of HTTP (for example, firmware binaries).

Set the full URL to the proxyUri request option, including the protocol.

Proxying is limited to the following hosts:

• https://pgps.nrfcloud.com
• https://firmware.nrfcloud.com
• https://static.api.nrfcloud.com
• https://bundles.nrfcloud.com

The default block size is 1024, but can be defined in the CoAP request block size option.

Query parameters:

• offset=<byte offset> (optional): number of bytes from the start of the file to skip before beginning block transfer; optional; defaults to 0

Examples:

coap send --proxy-uri https://pgps.nrfcloud.com/public/16096-14400.bin GET "coaps://coap.nrfcloud.com/proxy" > 16096-14400.bin

coap send -b 512 --proxy-uri https://pgps.nrfcloud.com/public/16096-14400.bin GET "coaps://coap.nrfcloud.com/proxy" > 16096-14400.bin

coap send --proxy-uri https://firmware.nrfcloud.com/e07f25b0-a92b-4043-af5e-d556700daeee/APP9ad65d992.6.99/app_update.bin GET "coaps:///coap.nrfcloud.com/proxy?offset=10475760" > app_update-remainder.bin