GraphQL API overview

The GraphQL read surface for querying building data.

Endpoint

POST https://app.betacit.com/graphql

All GraphQL requests use a single endpoint with POST method.

Multi-tenant scoping

All root queries require a siteId parameter that scopes the query to a specific site (building portfolio). This is your multi-tenant boundary. Each site has its own knowledge graph.

{
  building(siteId: "your-site-id") {
    id
    name
  }
}

For brevity, most examples in these docs omit the siteId parameter. In practice, every root query (building, equipment, point, zone, system, location) requires it.

Request format

curl -X POST https://app.betacit.com/graphql \
  -H "Authorization: Bearer $TACIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ building(siteId: \"your-site-id\") { id name } }",
    "variables": {}
  }'

Response format

{
  "data": { ... },
  "errors": [ ... ]
}

Successful queries return data in the data field. Errors appear in the errors array.

Key features

The GraphQL surface provides five semantic capabilities powered by Brick Schema:

• Name-based discovery: find any entity by name without knowing its UUID. name: "AHU" returns all matching equipment with case-insensitive substring search
• Class hierarchy inference: the is argument resolves Brick class hierarchies. is: "HVAC_Equipment" matches AHUs, VAVs, chillers, pumps, and every subtype
• Cross-cutting queries: combine locationName, equipmentIs, and is to query across the entire building graph in a single request. “Temperature sensors on VAVs in Tower East” is one query
• Transitive traversal: upstream and downstream fields follow equipment chains to any depth, with optional medium and maxDepth filtering
• Structured properties: equipment metadata (controller name, point count, virtual flag) as typed EntityProperty objects with hasProperty / propertyValue filtering

Rate limits

The API enforces per-client rate limits to ensure fair usage:

Client type	Limit
API key	2400 requests/minute
Authenticated user	1200 requests/minute
Anonymous	120 requests/minute

When the limit is exceeded, the API returns HTTP 429 with a Retry-After header. GraphQL responses include a standard errors array.

When to use GraphQL

Use GraphQL for all building data queries: buildings, equipment, points, zones, and their relationships. Use the REST timeseries endpoint for historical sensor data.

See relationships and traversal for the most powerful query patterns.