Skip to content
Guides & References

Call the rConfig API with curl and jq

Try rConfig REST API endpoints from a shell with curl and jq: the apitoken header, a connection test, paging through lists and failing on errors.

API & DeveloperUpdated
On this page

Call the rConfig API with curl and jq

curl is the quickest way to try an endpoint, and with jq it’s enough for small shell scripts and CI steps. This page covers the calls you’ll use most, a loop that follows every page of a list, and the flags that make a script fail properly when something goes wrong.


Set it up

Terminal window
sudo dnf install curl jq # RHEL family
sudo apt install curl jq # Ubuntu
export RCONFIG_URL=https://rconfig.example.com
read -rs RCONFIG_TOKEN && export RCONFIG_TOKEN # paste the token; it isn't echoed or saved in history

Single calls

Terminal window
# Test the token (needs no ability)
curl -sS --fail-with-body -H "apitoken: $RCONFIG_TOKEN" "$RCONFIG_URL/api/v2/apitest"
# One device, without its stored credentials
curl -sS --fail-with-body -H "apitoken: $RCONFIG_TOKEN" \
"$RCONFIG_URL/api/v2/devices/12?with_credentials=false" \
| jq '{name: .device_name, status: .last_backup_status, at: .last_backup_at}'
# Backup summary across the estate
curl -sS --fail-with-body -H "apitoken: $RCONFIG_TOKEN" "$RCONFIG_URL/api/v2/devices/summary" | jq .
# Start a backup now (returns as soon as it's queued)
curl -sS --fail-with-body -H "apitoken: $RCONFIG_TOKEN" "$RCONFIG_URL/api/v1/download-now/12"

Use -g (or --globoff) when a URL has square brackets, such as filter[device_id]=12, so curl doesn’t read them as a pattern:

Terminal window
curl -sS -g --fail-with-body -H "apitoken: $RCONFIG_TOKEN" \
"$RCONFIG_URL/api/v2/configs?filter[device_id]=12&perPage=5" | jq '.data[] | {id, command, created_at}'

Every page of a list

rconfig-all-devices.sh
#!/usr/bin/env bash
# Print every device rConfig returns, following every page.
set -o pipefail
: "${RCONFIG_URL:?set RCONFIG_URL}" "${RCONFIG_TOKEN:?set RCONFIG_TOKEN}"
page=1
while :; do
body=$(curl -sS --fail-with-body --max-time 60 \
-H "apitoken: $RCONFIG_TOKEN" \
"$RCONFIG_URL/api/v2/devices?per_page=100&page=$page&with_credentials=false") \
|| { echo "request failed on page $page: $body" >&2; exit 1; }
printf '%s' "$body" | jq -r '.data[] | [.id, .device_name, .device_ip, (.last_backup_at // "never")] | @tsv'
[ "$(printf '%s' "$body" | jq -r '.next_page_url')" = "null" ] && break
page=$((page + 1))
done

Habits that matter

  • --fail-with-body. Makes curl exit non-zero on an HTTP error while still printing the error body. Plain curl exits 0 on a 403. (Needs curl 7.76 or later; on older versions use --fail.)
  • --max-time. A stalled request otherwise hangs the script.
  • The header, not the URL. ?apitoken= works, but the token then lands in shell history, proxy logs and web server logs.
  • jq -S sorts keys, which makes saved responses easy to compare.

Type to search.