> 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/call-the-api.md).

# Call the API

Each example discovers an organization and hall, selects a registered sensor, and reads up to ten uncompensated raw frames from the last five minutes. The token stays in an environment variable and is never printed.

## Before you run an example

Store the once-only token outside the project, restrict the file, then load it into the current process. Do not commit either the token or an `.env` file that contains it.

```bash
install -d -m 700 "$HOME/.config/butlr"
chmod 600 "$HOME/.config/butlr/organization-api.token"
export BUTLR_DC_API_TOKEN="$(<"$HOME/.config/butlr/organization-api.token")"
export BUTLR_DC_API_BASE='https://api.datacenter.butlr.io'
```

{% hint style="info" %}
The commands assume the token file already exists. Paste the token into it with a trusted local editor or secret-management workflow; do not put the plaintext on a shell command line. The examples use the first returned hall and first supported sensor. Set `BUTLR_DC_HALL_ID` to choose a specific hall.
{% endhint %}

## Shell

Requires Bash or Zsh, `curl`, and `jq`.

```bash
#!/usr/bin/env bash
set -euo pipefail

: "${BUTLR_DC_API_TOKEN:?Set BUTLR_DC_API_TOKEN first}"
BUTLR_DC_API_BASE="${BUTLR_DC_API_BASE:-https://api.datacenter.butlr.io}"

graphql() {
  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 "$1"
}

inventory=$(graphql '{"query":"query OrganizationInventory { orgs { id name } dataHalls { id name } }"}')
if jq -e '.errors | length > 0' >/dev/null 2>&1 <<<"$inventory"; then
  jq '.errors' <<<"$inventory" >&2
  exit 1
fi

hall_id="${BUTLR_DC_HALL_ID:-$(jq -er '.data.dataHalls[0].id' <<<"$inventory")}"
sensor_request=$(jq -cn --arg hallId "$hall_id" '{
  query: "query HallSensors($hallId: ID!) { sensors(hallId: $hallId) { id kind mac serial model status } }",
  variables: {hallId: $hallId}
}')
sensors=$(graphql "$sensor_request")
if jq -e '.errors | length > 0' >/dev/null 2>&1 <<<"$sensors"; then
  jq '.errors' <<<"$sensors" >&2
  exit 1
fi

sensor_key=$(jq -er 'first(
  .data.sensors[] |
  if .kind == "wireless_mac" then .mac
  elif .kind == "wired_serial" then .serial
  else empty end |
  select(. != null and . != "")
)' <<<"$sensors")

to_ms="$(( $(date +%s) * 1000 ))"
from_ms="$(( to_ms - 300000 ))"

curl --fail-with-body --silent --show-error --get \
  "$BUTLR_DC_API_BASE/v1/sensors/$sensor_key/frames" \
  --header "Authorization: Bearer $BUTLR_DC_API_TOKEN" \
  --data-urlencode "from=$from_ms" \
  --data-urlencode "to=$to_ms" \
  --data-urlencode 'limit=10' \
  --data-urlencode 'compensate=0' |
  jq '{key, kind, tier, from, to, count, total, sampled, missing, compensated}'
```

Remove the final `jq` projection when your application is ready to process the full `frames[].data` matrices.

## Python

Uses only the Python 3 standard library.

```python
import json
import os
import time
from urllib.parse import quote, urlencode
from urllib.request import Request, urlopen

BASE_URL = os.getenv("BUTLR_DC_API_BASE", "https://api.datacenter.butlr.io").rstrip("/")
TOKEN = os.environ["BUTLR_DC_API_TOKEN"].strip()


def request_json(url, *, payload=None):
    body = None if payload is None else json.dumps(payload).encode()
    request = Request(url, data=body)
    request.add_header("Authorization", f"Bearer {TOKEN}")
    if body is not None:
        request.add_header("Content-Type", "application/json")
    with urlopen(request, timeout=30) as response:
        return json.load(response)


def graphql(query, variables=None):
    result = request_json(
        f"{BASE_URL}/graphql",
        payload={"query": query, "variables": variables or {}},
    )
    if result.get("errors"):
        raise RuntimeError(json.dumps(result["errors"]))
    return result["data"]


inventory = graphql(
    "query OrganizationInventory { orgs { id name } dataHalls { id name } }"
)
hall_id = os.getenv("BUTLR_DC_HALL_ID") or inventory["dataHalls"][0]["id"]

sensors = graphql(
    """query HallSensors($hallId: ID!) {
      sensors(hallId: $hallId) { id kind mac serial model status }
    }""",
    {"hallId": hall_id},
)["sensors"]

sensor = next(
    sensor
    for sensor in sensors
    if (sensor.get("mac") if sensor["kind"] == "wireless_mac"
        else sensor.get("serial") if sensor["kind"] == "wired_serial"
        else None)
)
sensor_key = sensor["mac"] if sensor["kind"] == "wireless_mac" else sensor["serial"]

to_ms = int(time.time() * 1000)
query = urlencode({"from": to_ms - 300_000, "to": to_ms, "limit": 10, "compensate": 0})
frames = request_json(
    f"{BASE_URL}/v1/sensors/{quote(sensor_key, safe='')}/frames?{query}"
)

first_matrix = frames["frames"][0]["data"] if frames["frames"] else []
print(json.dumps({
    "organization": inventory["orgs"][0]["name"],
    "hall_id": hall_id,
    "sensor_key": sensor_key,
    "tier": frames["tier"],
    "count": frames["count"],
    "missing": frames["missing"],
    "matrix_rows": len(first_matrix),
    "matrix_columns": len(first_matrix[0]) if first_matrix else 0,
}, indent=2))
```

## JavaScript

Requires Node.js 18 or later for the built-in `fetch` implementation.

```javascript
const baseUrl = (process.env.BUTLR_DC_API_BASE ?? "https://api.datacenter.butlr.io")
  .replace(/\/$/, "");
const token = process.env.BUTLR_DC_API_TOKEN?.trim();
if (!token) throw new Error("Set BUTLR_DC_API_TOKEN first");

async function requestJson(url, init = {}) {
  const response = await fetch(url, {
    ...init,
    headers: {
      Authorization: `Bearer ${token}`,
      ...(init.body ? { "Content-Type": "application/json" } : {}),
      ...init.headers,
    },
  });
  const body = await response.json();
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${JSON.stringify(body)}`);
  return body;
}

async function graphql(query, variables = {}) {
  const result = await requestJson(`${baseUrl}/graphql`, {
    method: "POST",
    body: JSON.stringify({ query, variables }),
  });
  if (result.errors?.length) throw new Error(JSON.stringify(result.errors));
  return result.data;
}

const inventory = await graphql(
  "query OrganizationInventory { orgs { id name } dataHalls { id name } }",
);
const hallId = process.env.BUTLR_DC_HALL_ID ?? inventory.dataHalls[0].id;
const { sensors } = await graphql(
  `query HallSensors($hallId: ID!) {
    sensors(hallId: $hallId) { id kind mac serial model status }
  }`,
  { hallId },
);

const sensor = sensors.find((candidate) =>
  candidate.kind === "wireless_mac" ? candidate.mac
    : candidate.kind === "wired_serial" ? candidate.serial
      : false,
);
if (!sensor) throw new Error("No supported sensor was returned for this hall");
const sensorKey = sensor.kind === "wireless_mac" ? sensor.mac : sensor.serial;

const to = Date.now();
const query = new URLSearchParams({
  from: String(to - 300_000),
  to: String(to),
  limit: "10",
  compensate: "0",
});
const frames = await requestJson(
  `${baseUrl}/v1/sensors/${encodeURIComponent(sensorKey)}/frames?${query}`,
);

const firstMatrix = frames.frames[0]?.data ?? [];
console.log(JSON.stringify({
  organization: inventory.orgs[0].name,
  hallId,
  sensorKey,
  tier: frames.tier,
  count: frames.count,
  missing: frames.missing,
  matrixRows: firstMatrix.length,
  matrixColumns: firstMatrix[0]?.length ?? 0,
}, null, 2));
```

## Production safeguards

* Keep the token in a server-side process. Never run these calls from a public browser bundle.
* Re-run discovery instead of assuming that hall ownership or sensor registration never changes.
* Keep `compensate=0` when the integration needs the original device matrix.
* Treat an empty frame window as a valid `200` response and inspect `missing`.
* Use bounded windows and deliberate polling; the archive endpoint is not a live stream.
* [Authentication](https://docs.butlr.io/data-center/authentication.md) — Protect, rotate, and revoke an Organization API Token.
* [Raw frame contract](https://docs.butlr.io/data-center/read-raw-frames.md) — Review response fields, limits, and matrix format.
