Read, write and invoke

These calls use an API key with the matching permissions. See Create an API key with permissions. The examples keep the key and a Nodelet ID in variables:

export NODELETS_KEY='nlt_...'
export NODELET='nl_5c0e8a2f-7d41-4b9e-a3c6-2f8d1e4b7a90'
API=https://api.staging.nodelets.com

Find the Nodelet and what it can do

curl -fsS -H "Authorization: Bearer $NODELETS_KEY" $API/nodelets
curl -fsS -H "Authorization: Bearer $NODELETS_KEY" $API/nodelets/$NODELET/td

The listing gives each Nodelet’s ID and name. The Thing Description lists the properties, actions and events the key may use, each with its schema and the URL to call. The dashboard’s Bridges page shows the same capabilities, and a card’s details drawer has a button to copy the Nodelet ID.

Read a property

Needs Read value.

curl -fsS -H "Authorization: Bearer $NODELETS_KEY" \
  $API/nodelets/$NODELET/properties/setpoint

21

The answer is the bare JSON value, read from the device for this request and checked against the definition. Nothing is cached.

Write a property

Needs Write value. Send the new value as the JSON body:

curl -fsS -X PUT -H "Authorization: Bearer $NODELETS_KEY" \
  -d '22' \
  $API/nodelets/$NODELET/properties/setpoint

null

null means the device accepted the write. Nodelets does not read the value back; read it again if you need to see it.

A string is sent as JSON too, so a mode is written as -d '"eco"'. An object is written whole: -d '{"x": 0.7, "y": 0.3}'.

Invoke an action

Needs Run action. Send the action’s input as the JSON body, or no body for an action with no input:

curl -fsS -X POST -H "Authorization: Bearer $NODELETS_KEY" \
  -d '{"minutes": 15}' \
  $API/nodelets/$NODELET/actions/boost

{"until": "2026-11-07T15:45:00Z"}

The answer is the action’s declared output, or null for an action with none.

When an operation fails

A failed call answers with an HTTP error status and a body like this:

{"error":{"code":"OUTCOME_UNKNOWN","message":"OUTCOME_UNKNOWN","correlationId":"req_...","outcome":"unknown"}}

Act on outcome first:

• not-executed: the device did not act. It is safe to try again.
• unknown: the write or action may have reached the device, but nothing confirmed it. Read the property, or check the device, before you try again. Sending the same request again sends a second command.
• No outcome: the call failed before reaching a device, or it is a read, which changes nothing.

Each operation is sent once and never resent by Nodelets. A call has a deadline of 10 seconds. A read that runs out of time is TIMEOUT; a write or action that runs out of time is OUTCOME_UNKNOWN.

See Outcomes and errors for every code.

Limits

• A request body is at most 256 KiB.
• A bridge holds at most 64 commands in flight. Past that, a call answers BUSY with outcome not-executed.
• Every call crosses the cloud and the bridge’s connection. Do not use Nodelets for control loops or safety functions.