Query API

Consumers read inventories through a REST API that returns JSON. This section explains how to list and filter entities, how HFIDs identify them, and how to read the completeness, health, freshness and source information that every response carries.

The running server also serves a reference generated from its handlers:

• /docs: the interactive API reference, with every route, parameter and response body.
• /openapi.json: the OpenAPI document, for generating a client.

Conventions

• Every route is a GET, except the webhook receiver. The API cannot change data or configuration.
• There is no authentication. Census runs on a trusted network.
• Every timestamp is RFC 3339 in UTC with microseconds, for example 2026-10-25T09:00:00.123456Z.
• Census rejects a query parameter it does not know with 400 invalid-query, instead of ignoring it.
• No response contains a source system's endpoint or credentials.

Routes

Route	Purpose	Page
GET /v1/inventories	List inventories with their status and completeness	Discover inventories
GET /v1/inventories/{inventory}	Read an inventory's definition	Discover inventories
GET /v1/inventories/{inventory}/locations	Read the location hierarchy	Discover inventories
GET /v1/inventories/{inventory}/entities	List entities with filters, sorting and pages	Query entities
GET /v1/inventories/{inventory}/entities/{hfid}	Read one entity by HFID	Identify an entity by its HFID
GET /v1/inventories/{inventory}/diagnostics	List excluded records and unusable values	Read diagnostics
GET /v1/connections	List source connections and the contributions that use them	Discover inventories
GET /healthz	200 when Census can reach its cache, otherwise 503
POST /webhooks/{connection}	Receive a source webhook	Keep inventories up to date

What every inventory response contains

Entity lists and lookups report, once per response:

• completeness: whether the inventory holds every source's data, and the causes when it does not. Completeness and contribution health explains it.
• The health of each contribution: contributions in a list, health in a lookup.
• view: the branch the response reads, and what each contribution supplied. Query a branch explains it.

Each entity reports its resolved values, the contribution that supplied each value, its location and its freshness. With detail=full, it also reports where each value came from: Trace a value to its source.

Errors

Errors use the RFC 7807 problem format, with a type per case, for example inventory-incomplete or branch-not-found. Errors lists every case.