> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/data-center/quickstart.md).

# 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.

```bash
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

```bash
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:

```bash
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.

```bash
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. Matrix dimensions depend on the sensor model (8 x 8 for Heatic 2+ and 40 x 60 for Heatic 3), so read the returned array dimensions rather than assuming one shape.

{% hint style="warning" %}
The device timestamp is not a guarantee of freshness. Compare it with your request time and monitor `missing`, `count`, and `total`.
{% endhint %}

Next: [Copy a complete integration](https://docs.butlr.io/data-center/call-the-api.md) that discovers a hall and sensor before reading raw frames.
