Queries

WarmHub reads come in a few shapes — a HEAD snapshot, a targeted get, a filtered query, search, and history. This page runs the most common one; the table routes you to the rest.

Run a query

Read the active things of a shape from any repo:

wh thing query --repo warmhub-data/us.congress --shape Legislator

Add --json for structured output, --count for just the total, or --about <wref> to find the assertions that target a thing. The full filter grammar, search modes, collection resolution, version history, and active-vs-retracted semantics live in Filtering & Query Modes.

Query types

Query	Use case	CLI	MCP Tool
HEAD	Snapshot of all active entities	wh thing list	warmhub_thing_head
Count	Count matching items without fetching data	wh thing list --count	warmhub_thing_head with count: true
Get	Fetch a specific thing by wref	wh thing view	warmhub_thing_get
Query	Filter by shape, kind, about	wh thing query	warmhub_thing_query
About	Assertions whose about target resolves to a target identity	wh thing about <wref> or wh assertion list --about <wref>	warmhub_thing_about
History	Version history of a thing	wh thing history	warmhub_thing_history
Resolve	Resolve wref to identity	wh thing resolve	warmhub_wref_resolve
Search	Find things by text content	wh thing search	warmhub_thing_search
Get Many	Batch lookup by wrefs	wh thing view [wrefs...]	warmhub_thing_get_many
Refs	Backlinks and cross-references	wh thing refs	warmhub_thing_refs

Use wh thing about <wref> when starting from a thing and asking what assertions directly target it. wh assertion list --about <wref> is the equivalent assertion-domain form when you are already browsing assertions.

Access methods

The same queries are available across three surfaces — pick what fits your workflow:

• CLI: wh <domain> <verb> [args] [--flags] — human-readable output, or --json for structured data
• MCP: warmhub_* tools — typed JSON-RPC tool calls
• HTTP API: GET /api/repos/:org/:repo/<endpoint> — RESTful queries with query parameters

Where to next

Need	Page
A point-in-time snapshot of all active entities	Head
Filter by shape / kind / about, search modes, version history, batch lookup, collection resolution, active-vs-retracted	Filtering & Query Modes