Transitioning the REST API

If you use the legacy nRF Cloud REST API, this guide explains how to migrate your device integrations to the API used by the new nRF Cloud experience. It maps legacy endpoints to their replacements and describes the changes to requests and responses.

info

The legacy REST API continues to work during the transition, so you can migrate one endpoint at a time.

This guide covers only endpoints that are available in the new nRF Cloud API today. Deprecated endpoints with no planned replacement are listed in Endpoints without a replacement.

What is changing

Both APIs use https://api.nrfcloud.com. Authentication and the way you scope requests to devices have changed.

Aspect	Legacy nRF Cloud REST API	nRF Cloud API
API host	api.nrfcloud.com	api.nrfcloud.com (unchanged)
Authentication	API key	Organization auth token (OAT)
Scope	The team that owns the API key	An organization and a project, both specified in the URL
URL prefix	/v1/	/v1/organizations/<ORG>/projects/<PROJECT>/
Permissions	The API key owner's role in the team	OAT permissions, such as device:read and device:write

Before you begin

You need:

• An organization auth token with the permissions required by the endpoints you call. Each endpoint's API reference lists the permission it requires. Organization admins create tokens under Admin → Organization Auth Tokens → Create Token. See Organization Auth Tokens.
• Your organization slug and project slug, both of which appear under Project Settings → General.

The following examples assume your OAT, organization slug, and project slug are available as the environment variables NRFCLOUD_OAT, NRFCLOUD_ORG, and NRFCLOUD_PROJECT, respectively. For requests that target a single device, set DEVICE_ID to its nRF Cloud device ID.

Set BASE to the project-scoped URL prefix:

BASE="https://api.nrfcloud.com/v1/organizations/$NRFCLOUD_ORG/projects/$NRFCLOUD_PROJECT"

Send the OAT in the Authorization header using the Bearer scheme, as you did with the API key:

-H "Authorization: Bearer $NRFCLOUD_OAT"

Endpoint mapping

Paths in the nRF Cloud API column are relative to /v1/organizations/<ORG>/projects/<PROJECT>.

Task	Legacy nRF Cloud REST API	nRF Cloud API
Retrieve a device	GET /v1/devices/{deviceId}	GET /devices/{deviceId}
List devices	GET /v1/devices	GET /devices
Rename a device	PUT /v1/devices/{deviceId}/name	PATCH /devices/{deviceId}
Onboard a device	POST /v1/devices/{deviceId}	POST /long-range/devices
Onboard devices in bulk	POST /v1/devices	POST /long-range/devices/bulk
Register device certificates	POST /v1/devices/certificates	POST /long-range/devices/bulk
Track a bulk operation	GET /v1/bulk-ops-requests/{id}	Follow the URL returned by the bulk call
Delete a device	DELETE /v1/devices/{deviceId}	DELETE /long-range/devices/{deviceId}
Retrieve the device state	GET /v1/devices/{deviceId}	GET /long-range/devices/{deviceId}/state
Update the device state	PATCH /v1/devices/{deviceId}/state	PATCH /long-range/devices/{deviceId}/state
Publish a device message	POST /v1/devices/{deviceId}/messages	POST /long-range/devices/{deviceId}/mqtt-message
List stored device messages	GET /v1/messages	GET /messages

The sections below describe the differences for each task.

Devices

Retrieve, list, and rename devices

Use the Devices API in the new nRF Cloud experience to retrieve, list, and rename devices. This API covers all devices in the project.

In this API, the nRF Cloud device ID is the device serial (device_serial).

To retrieve a device:

curl "$BASE/devices/$DEVICE_ID" \
  -H "Authorization: Bearer $NRFCLOUD_OAT"

The response uses the Devices API's device format. For example, the device ID is returned as device_serial, and the device belongs to a cohort instead of having tags. See Retrieve a Device.

The legacy endpoint also returned the device state. To retrieve it, use the device state endpoint. The transform query parameter is also available at that endpoint.

To list devices:

curl "$BASE/devices" \
  -H "Authorization: Bearer $NRFCLOUD_OAT"

The legacy filters, such as tags, subTypes, firmwareSupport, and deviceNameFuzzy, and the transform parameter are not available. See List Devices for the supported parameters and the response format.

To rename a device, set its nickname instead of sending the new name to the legacy /name endpoint:

curl -X PATCH "$BASE/devices/$DEVICE_ID" \
  -H "Authorization: Bearer $NRFCLOUD_OAT" \
  -H "Content-Type: application/json" \
  -d '{"nickname": "warehouse-east-01"}'

See Update a Device.

Onboard devices

Secure Device Onboarding walks through onboarding a single device or a batch of devices with the nRF Cloud API, including tracking a bulk upload and reviewing failed rows. This section describes the changes from the legacy onboarding endpoints.

Both the single-device and bulk endpoints accept exactly one credential per device:

Device	Credential	Single-device body fields	Bulk CSV columns
nRF9160	Certificate	deviceId and certificate	deviceId and certificate
nRF9151, nRF9161	Attestation token	attestationToken	deviceId and attestationToken
nRF93M1	Onboarding token	onboardingToken, optional deviceId	deviceId and onboardingToken

Differences from the legacy endpoints:

• For a single device, the device ID moves from the URL into the request body, or is read from the token. The response is 200 OK with the onboarded device ID, instead of an empty 202 Accepted.
• subType, tags, and supportedFirmwareTypes are not accepted, either as body fields or as CSV columns. New devices start in the default cohort; see Cohorts.
• For certificate-based onboarding, submit a certificate, not a public key.
• The bulk CSV requires a header row. The legacy endpoint accepted files without one.
• The bulk response includes a URL for tracking the upload in both the Location header and the response body, rather than only a bulkOpsRequestId.

For example, use the following request body to onboard a single nRF9160 device:

{
  "deviceId": "cafe0001-0000-0000-0000-000000000001",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==\n-----END CERTIFICATE-----\n"
}

For bulk onboarding of nRF9160 devices, use the following CSV format:

deviceId,certificate
cafe0001-0000-0000-0000-000000000001,"-----BEGIN CERTIFICATE-----
MIIB7DCCAZMCFD...Av3CVgjzn5BLS03X7lyf4w==
-----END CERTIFICATE-----
"

See Create an nRF9x Device and Create nRF9x Devices in Bulk.

Register device certificates

There is no separate certificate registration endpoint. Submit the certificates to the bulk onboarding endpoint instead, using the deviceId,certificate format in Onboard devices.

Onboarding is idempotent. For a device that is already onboarded to your project, a row with a new certificate replaces the device's existing certificate, as the legacy endpoint did. A device that is not yet onboarded is onboarded with the certificate.

Track a bulk operation

Instead of constructing a bulk-ops-requests URL from the request ID, follow the URL returned by the bulk onboarding request, as described in Follow the upload to completion. The status response differs from the legacy response:

Legacy field	nRF Cloud API
errorSummaryUrl	Replaced by errorSummary, included in the response when status is FAILED
uploadedDataUrl	Unchanged; download the CSV with an OAT that has the device:write permission
bulkOpsRequestId, endpoint	Not returned

For the format of errorSummary, see Review failed rows.

Delete a device

curl -X DELETE "$BASE/long-range/devices/$DEVICE_ID" \
  -H "Authorization: Bearer $NRFCLOUD_OAT"

Deleting a device also releases its claim, so another project can onboard it. Deletion is idempotent: deleting a device that does not exist also returns 202 Accepted.

See Delete an nRF9x Device.

Device state

Retrieve the device state

The legacy API returned the state as part of the device response. In the new API, the state has a dedicated endpoint:

curl "$BASE/long-range/devices/$DEVICE_ID/state" \
  -H "Authorization: Bearer $NRFCLOUD_OAT"

The response contains reported, desired, delta, metadata, and version. The transform query parameter accepts a JSONata expression, as before, but it is evaluated against this state object rather than the whole device.

See Retrieve the State of an nRF9x Device.

Update the device state

The request body is unchanged: a patch with desired, reported, or both.

curl -X PATCH "$BASE/long-range/devices/$DEVICE_ID/state" \
  -H "Authorization: Bearer $NRFCLOUD_OAT" \
  -H "Content-Type: application/json" \
  -d '{"desired": {"control": {"logLvl": 3}}}'

Differences:

• The patch is validated before it is applied. Paths owned by the platform, such as pairing, connection, and desired.device, are rejected unless you add force=true to the query string, and some paths have a required value type. All violations are reported in a single 422 Unprocessable Entity response, and the state remains unchanged.
• The If-Match header is ignored. The patch is always merged into the current state.

See Update the State of an nRF9x Device for the full list of constrained paths.

Messages

Publish a device message

Like the legacy endpoint, the new endpoint publishes an MQTT message on behalf of a device. The legacy topic was relative to <mqttTopicPrefix>/m/, so it could name any topic. The new endpoint publishes only to the device's own topics, <mqttTopicPrefix>/m/d/<deviceId>/<subtopic>, and rejects devices that connect over CoAP.

The request body has changed:

Legacy field	nRF Cloud API
topic	subtopic: the part after d/<deviceId>/, for example d2c instead of d/<deviceId>/d2c
message	payload for a JSON object or array, or payloadBase64 for binary data
—	contentType (optional): the MQTT content type of the published message

curl -X POST "$BASE/long-range/devices/$DEVICE_ID/mqtt-message" \
  -H "Authorization: Bearer $NRFCLOUD_OAT" \
  -H "Content-Type: application/json" \
  -d '{"subtopic": "d2c", "payload": {"appId": "TEMP", "messageType": "DATA", "data": "23.5"}}'

This example publishes to the device-to-cloud topic, as if the device had sent the message. To deliver a message to a device that uses the nRF Cloud library, publish to its receive topic, c2d/r, instead.

The device ID comes from the URL. A subtopic that starts with the device ID or with d/<deviceId> is rejected. The subtopic must have one to three levels, and the full topic must not exceed 256 bytes. The 202 Accepted response contains the full MQTT topic to which the message was published.

See Publish an MQTT Message for an nRF9x Device.

List stored device messages

curl "$BASE/messages?deviceId=$DEVICE_ID" \
  -H "Authorization: Bearer $NRFCLOUD_OAT"

The following filter and pagination parameters are unchanged: deviceId, appId, topic, start, end, pageLimit, pageSort, and pageNextToken. The same filter combinations are supported: topic requires deviceId and cannot be combined with appId.

Differences from the legacy endpoint:

• The deprecated inclusiveStart and exclusiveEnd parameters are removed. Use start and end.
• Messages in the response no longer include tenantId.

See List nRF9x Device Messages.

Endpoints without a replacement

The following legacy endpoints are deprecated and have no planned replacement in the nRF Cloud API. Where an alternative workflow is available in the new nRF Cloud experience, it is listed below.

Legacy endpoint	What to use instead
GET /v1/devices/tags, PUT /v1/devices/{deviceId}/tags	Tags are replaced by cohorts.
/v1/devices/{deviceId}/image	No replacement.
POST /v1/devices/{deviceId}/certificates (just-in-time provisioning)	No replacement. Onboard the device with its certificate, as described in Onboard devices.
PUT /v1/association/{deviceId}	No replacement.
POST /v1/identities/verify-jwt	No replacement.
/v1/alerts	No replacement.
/v1/binary-logs	No replacement. The endpoint already returns 410 Gone.
/v1/firmwares, /v1/fota-jobs, /v1/fota-job-executions, /v1/fota-job-execution-statuses, and subpaths	OTA updates in the new nRF Cloud experience. See New FOTA Experience.
/v1/imei-management/...	The nRF Cloud application.

The following Provisioning Service endpoints at api.provisioning.nrfcloud.com are also deprecated:

Legacy endpoint	What to use instead
/v1/claimed-devices/...	Adding a device claims it, and deleting it releases the claim. See Secure Device Onboarding.
/v1/provisioning-rules/...	Not needed. Adding a device onboards it. See Secure Device Onboarding.
/v1/provisioning/...	No replacement.