Skip to main content

Lesson 3.6 Curl

curl makes the same IoT platform REST API calls as Postman, but straight from the command line - ideal for quick tests and for scripting or automation. This lesson mirrors the Postman lesson using curl.

Examples use two shell variables so you don't repeat yourself:

export YGGIO_URL="staging.yggio.net"

Exercise 1 - Get an access token​

curl -sS -X POST "https://$YGGIO_URL/api/auth/local" \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

The response is { "token": "eyJ..." }. Capture it into a variable (with jq):

export YGGIO_TOKEN=$(curl -sS -X POST "https://$YGGIO_URL/api/auth/local" \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}' | jq -r .token)

All authenticated calls then use the header Authorization: Bearer $YGGIO_TOKEN.

Exercise 2 - List your devices​

curl -sS "https://$YGGIO_URL/api/iotnodes" \
  -H "Authorization: Bearer $YGGIO_TOKEN" | jq .

Filter to devices that have a field, e.g. temperature:

curl -sS "https://$YGGIO_URL/api/iotnodes?q=temperature" \
  -H "Authorization: Bearer $YGGIO_TOKEN" | jq '.[].name'

Exercise 3 - Push a value to a generic device​

Create a Generic device with a secret first (see Lesson 2.3). This endpoint authenticates with the device secret, not the Bearer token:

curl -sS "https://$YGGIO_URL/http-push/generic?identifier=secret" \
  -H "Content-Type: application/json" \
  -d '{
        "secret": "YOURDEVICESECRET",
        "temperature": 22,
        "relativeHumidity": 48
      }'

The device updates in the IoT platform.

Exercise 4 - Update a device (add / remove a field)​

Use PUT /api/iotnodes/{_id} with the Bearer token, e.g. to add a temporary secret (as used for CSV time-series import) and later remove it:

# add a secret
curl -sS -X PUT "https://$YGGIO_URL/api/iotnodes/DEVICE_ID" \
  -H "Authorization: Bearer $YGGIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret":"TEMP_SECRET"}'

# remove it again
curl -sS -X PUT "https://$YGGIO_URL/api/iotnodes/DEVICE_ID" \
  -H "Authorization: Bearer $YGGIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secret":"$unset"}'

Tip: pipe responses through jq for readable JSON, and keep your token in an environment variable rather than pasting it into every command.

What you learned​

  • How to get a token (POST /api/auth/local) and pass it as Authorization: Bearer.
  • How to read (GET /api/iotnodes), push (POST /http-push/generic) and update (PUT /api/iotnodes/{_id}) from the command line.
  • How to script these calls with shell variables and jq.

Where next​