Queries

Query endpoints read data from a repository without modifying it. Public repositories can be queried without authentication.

To keep repository existence opaque, every deny path on these endpoints — anonymous requests against private repos, authenticated callers without sufficient scope, and lookups against missing repos — collapses to the same 404 response with Vary: Authorization. Authenticate with a token that has access to the repo to see real responses.

All paths are prefixed with /api/repos/:orgName/:repoName.

The currently mounted repository read routes are:

• GET /head
• GET /about/:wref
• GET /query

---

Anonymous Pagination Caps

Anonymous callers (no Bearer token) on the routes below are subject to narrowed paging to discourage bulk crawling of public repos:

• limit is capped at 25 items per page. Requests with limit > 25 return 400 with a VALIDATION_ERROR. When limit is omitted, anonymous callers get a 25-item page (authenticated callers continue to get the helper’s 50-item default).
• The page size is bound to the cursor. An anonymous follow-up that supplies nextCursor must either omit limit (and inherit the cursor’s page size) or pass the same limit used for the previous page. Mixing a different limit with nextCursor returns 400 with a VALIDATION_ERROR.
• Anonymous pagination stops after 2 pages. Following nextCursor past the second page returns 404. Authenticate to continue paging.

Authenticated callers see no narrowing — they continue to use limit up to 500 and may follow nextCursor indefinitely.

---

Filtered Read Freshness

The endpoints on this page — GET /head, GET /about/:wref, and GET /query — all accept a match parameter for glob-filtered reads. A scoped Bearer token can also limit which wrefs a caller can see.

Filtered reads may lag briefly after a write while WarmHub updates its read indexes. Subsequent reads after the indexes catch up will see the new state. Unfiltered reads made with an unscoped token reflect the latest written data immediately.

---

GET /head

Return the current HEAD snapshot — the latest version of every active thing in the repository.

Filtered /head reads — either with an explicit match or on a scoped Bearer token — are subject to the freshness note above.

Query Parameters

Parameter	Type	Required	Description
shape	string	No	Filter by shape name
kind	string	No	Filter by kind: thing, assertion, shape, collection
match	string	No	Glob pattern to filter wrefs (* = one segment, ** = zero or more)
limit	integer	No	Maximum items per page (max 500). When omitted, WarmHub returns up to 50 items. Anonymous callers are capped — see Anonymous Pagination Caps.
cursor	string	No	Opaque pagination cursor from a previous nextCursor response. Anonymous callers are capped at two pages — see Anonymous Pagination Caps.

Response 200

{
  "items": [
    {
      "wref": "StockTrade/20030868/0",
      "name": "20030868/0",
      "kind": "thing",
      "active": true,
      "shapeName": "StockTrade",
      "version": 3,
      "data": {
        "owner": "spouse",
        "ticker": "ABBNY",
        "amount": "$1,001 - $15,000",
        "tx_type": "sale",
        "trade_date": "2025-08-08",
        "legislator_name": "Adam Smith"
      }
    }
  ],
  "nextCursor": "whc1_eyJ2Ijox..."
}

When there are more results, nextCursor contains an opaque token to pass as the cursor parameter on the next request. When all results have been returned, nextCursor is omitted.

For assertions, the response includes an aboutWref field referencing the target thing. aboutWref is omitted when the assertion’s target lives in a soft-deleted source repo — the canonical wref is suppressed rather than leaking the hidden repo’s identity.

Example

# All things in the StockTrade shape
curl "https://api.warmhub.ai/api/repos/warmhub-data/congress-trading/head?shape=StockTrade"

# All shapes in the repository
curl "https://api.warmhub.ai/api/repos/warmhub-data/congress-trading/head?kind=shape"

# Paginate through results
curl "https://api.warmhub.ai/api/repos/warmhub-data/congress-trading/head?shape=StockTrade&limit=20&cursor=whc1_eyJ2Ijox..."

GET /about/:wref

Get a thing and all assertions about it.

Filtered /about reads — either with an explicit match or on a scoped Bearer token — are subject to the freshness note above. Unfiltered /about requests reflect the latest written state immediately.

When the URL-encoded wref is canonical (wh:org/repo/...) and points at a private repo the caller cannot read, the route returns 404 — the response is intentionally indistinguishable from a missing target. The same gate applies to /query reads with an about=wh:... filter. See Wrefs — Visibility gate on resolution.

Path Parameters

Parameter	Type	Description
wref	string	URL-encoded wref of the target thing

Query Parameters

Parameter	Type	Required	Description
shape	string	No	Filter assertions by shape name
match	string	No	Glob pattern to filter assertion wrefs (* = one segment, ** = zero or more)
includeRetracted	boolean	No	Resolve a retracted target and include retracted assertions (default false)
resolveCollections	boolean	No	Include assertions about collections containing the target thing (default false)
depth	integer	No	Nesting depth for recursive assertion lookup
limit	integer	No	Maximum assertions to return (max 500). Anonymous callers are capped — see Anonymous Pagination Caps.
cursor	string	No	Opaque pagination cursor from a previous nextCursor response. Anonymous callers are capped at two pages — see Anonymous Pagination Caps.

Response 200

The example below uses IngestRecord + Assessment because /about returns assertions about a thing, and that’s the shape pair in warmhub-data/congress-trading that carries those relationships (a per-ingest data-quality check).

{
  "target": {
    "wref": "IngestRecord/qc-run/2026-05-15/r411b00",
    "name": "qc-run/2026-05-15/r411b00",
    "kind": "thing",
    "active": true,
    "shapeName": "IngestRecord",
    "version": 1
  },
  "assertions": [
    {
      "wref": "Assessment/2026-04-10/ticker-extraction-rate",
      "name": "2026-04-10/ticker-extraction-rate",
      "kind": "assertion",
      "active": true,
      "shapeName": "Assessment",
      "version": 1,
      "data": {
        "passed": true,
        "check_name": "ticker-extraction-rate",
        "rationale": "89.5% of trades have a ticker symbol (6841/7644)",
        "confidence": 0.8
      },
      "aboutWref": "IngestRecord/qc-run/2026-05-15/r411b00@v1",
      "children": []
    }
  ],
  "nextCursor": "whc1_eyJ2Ijox..."
}

Errors

Code	Status	Description
NOT_FOUND	404	Target thing not found, or the caller cannot access the repo
VALIDATION_ERROR	400	Missing or invalid wref

Example

# All assertions about a thing
curl "https://api.warmhub.ai/api/repos/warmhub-data/congress-trading/about/IngestRecord%2Fqc-run%2F2026-05-15%2Fr411b00"

# Only Assessment-shape assertions, including retracted
curl "https://api.warmhub.ai/api/repos/warmhub-data/congress-trading/about/IngestRecord%2Fqc-run%2F2026-05-15%2Fr411b00?shape=Assessment&includeRetracted=true"

---

GET /query

Query things by filters. Returns items matching the specified criteria.

Filtered /query reads — either with an explicit match or on a scoped Bearer token — are subject to the freshness note above.

Query Parameters

Parameter	Type	Required	Description
shape	string	No	Filter by shape name
about	string	No	Filter assertions by target wref
kind	string	No	Filter by kind: thing, assertion, shape, collection
match	string	No	Glob pattern to filter wrefs (* = one segment, ** = zero or more)
resolveCollections	boolean	No	When about is set, also include assertions about collections containing the target (default false)
includeRetracted	boolean	No	Include retracted items (default false)
limit	integer	No	Maximum items to return (max 500). Anonymous callers are capped — see Anonymous Pagination Caps.
cursor	string	No	Opaque pagination cursor from a previous nextCursor response. Anonymous callers are capped at two pages — see Anonymous Pagination Caps.

Response 200

{
  "items": [
    {
      "wref": "StockTrade/20030868/0",
      "name": "20030868/0",
      "kind": "thing",
      "active": true,
      "shapeName": "StockTrade",
      "version": 3,
      "data": { "ticker": "ABBNY", "amount": "$1,001 - $15,000", "tx_type": "sale" }
    }
  ],
  "nextCursor": "whc1_eyJ2Ijox..."
}

Example

# All things in the StockTrade shape
curl "https://api.warmhub.ai/api/repos/warmhub-data/congress-trading/query?shape=StockTrade&kind=thing"

# Assertions about a specific thing
curl "https://api.warmhub.ai/api/repos/warmhub-data/congress-trading/query?about=IngestRecord%2Fqc-run%2F2026-05-15%2Fr411b00&kind=assertion"