> 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/discover-sensors.md).

# Discover halls and sensors

The GraphQL endpoint is `POST /graphql`. Organization API Tokens can execute queries only; parsed mutations are rejected.

## Inventory query

```graphql
query OrganizationInventory {
  orgs {
    id
    name
  }
  dataHalls {
    id
    name
  }
}
```

`orgs` returns exactly the token's organization. `dataHalls` cannot enumerate another customer's halls even when a caller supplies a foreign organization ID.

## Sensor query

```graphql
query HallSensors($hallId: ID!) {
  sensors(hallId: $hallId) {
    id
    kind
    mac
    serial
    model
    status
  }
}
```

Variables:

```json
{
  "hallId": "dc_hall_REPLACE_ME"
}
```

For `wireless_mac`, use `mac` as the raw-frame path key. For `wired_serial`, use `serial`. Refresh discovery rather than hard-coding a fleet: registrations and ownership can change.

{% hint style="warning" %}
A sensor must have one current, non-retired owner matching the token's organization. Unknown keys, historical ownership, and ambiguous registrations are denied.
{% endhint %}
