Quickstart

1. Store the token

Create a token in Data Center > Settings > API tokens, copy it once, and store it in a server-side secret manager.

export BUTLR_DC_API_BASE='https://api.datacenter.butlr.io'
export BUTLR_DC_API_TOKEN="$(<"$HOME/.config/butlr/organization-api.token")"

Never put the token in browser code, source control, URLs, screenshots, tickets, or logs. Restrict the token file to its owner with chmod 600 before loading it.

2. Discover halls

curl --fail-with-body --silent --show-error \
  "$BUTLR_DC_API_BASE/graphql" \
  --header "Authorization: Bearer $BUTLR_DC_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"query":"query Inventory { orgs { id name } dataHalls { id name } }"}'

The response contains only the organization bound to the token and its halls.

3. Discover sensors

Use a returned hall ID:

export BUTLR_DC_HALL_ID='dc_hall_REPLACE_ME'

curl --fail-with-body --silent --show-error \
  "$BUTLR_DC_API_BASE/graphql" \
  --header "Authorization: Bearer $BUTLR_DC_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{\"query\":\"query HallSensors { sensors(hallId: \\\"$BUTLR_DC_HALL_ID\\\") { id kind mac serial model status } }\"}"

Use mac for a wireless sensor or serial for a wired sensor in frame reads.

4. Read a recent window

from and to are Unix timestamps in milliseconds. This example downloads up to ten frames from the last five minutes.

export BUTLR_DC_SENSOR_KEY='REPLACE_WITH_MAC_OR_SERIAL'
export BUTLR_DC_TO_MS="$(( $(date +%s) * 1000 ))"
export BUTLR_DC_FROM_MS="$(( BUTLR_DC_TO_MS - 300000 ))"

curl --fail-with-body --silent --show-error \
  "$BUTLR_DC_API_BASE/v1/sensors/$BUTLR_DC_SENSOR_KEY/frames?from=$BUTLR_DC_FROM_MS&to=$BUTLR_DC_TO_MS&limit=10&compensate=0" \
  --header "Authorization: Bearer $BUTLR_DC_API_TOKEN"

A successful response includes the sensor key, archive tier, window, counts, and an ordered frames array. compensate=0 guarantees the returned data matrix is the raw device field. Each frame contains timestamp, Celsius min_c/max_c, and a data matrix of deciKelvin integers.

Copy a complete integration

Continue with an end-to-end Shell, Python, or JavaScript example that discovers a hall and sensor before reading raw frames.