Skip to main content

​
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 typeLimit
API key2400 requests/minute
Authenticated user1200 requests/minute
Anonymous120 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 queries reference for the complete list of root queries and their arguments.