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

Each item in items includes the fields listed below, plus a metadata object that carries a stable durable identifier and creation timestamps. All timestamp fields are epoch-millisecond numbers.

Field	Type	Description
wref	string	The thing’s wref within this repo
name	string	The name segment of the wref
kind	string	One of thing, assertion, shape, collection
active	boolean	false when the item has been retracted
shapeName	string	Name of the shape this item conforms to
version	integer	Current version number
createdAt	number (epoch ms)	Timestamp when this version was written (same value as metadata.revisedOn)
data	object	Shape-defined payload
componentRef	string	Present when the item is owned by an installed component; omitted otherwise
metadata.durableId	string	Stable, repo-scoped identifier that survives renames
metadata.createdOn	number (epoch ms)	Timestamp when the thing was first created
metadata.revisedOn	number (epoch ms)	Timestamp when this specific version was written

{
  "items": [
    {
      "wref": "StockTrade/20030868/0",
      "name": "20030868/0",
      "kind": "thing",
      "active": true,
      "shapeName": "StockTrade",
      "version": 3,
      "createdAt": 1723194344000,
      "data": {
        "owner": "spouse",
        "ticker": "ABBNY",
        "amount": "$1,001 - $15,000",
        "tx_type": "sale",
        "trade_date": "2025-08-08",
        "legislator_name": "Adam Smith"
      },
      "metadata": {
        "durableId": "dbl_01jt2k8mxe000000000000000a",
        "createdOn": 1723126921000,
        "revisedOn": 1723194344000
      }
    }
  ],
  "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 shape or shaped 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 CongressTrade shape
curl "https://api.warmhub.ai/api/repos/warmhub-data/us.congress.trades/head?shape=CongressTrade"

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

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

GET /about/:wref

Get a shape or shaped 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 shape or shaped 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). When combined with depth > 1, retracted assertions are also included in nested children arrays.
resolveCollections	boolean	No	Include assertions about collections containing the target entity (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 response contains a target object representing the looked-up shape or shaped thing, and an assertions array. All timestamp fields are epoch-millisecond numbers.

The target object contains the following fields:

Field	Type	Description
target.wref	string	The target’s wref within this repo
target.pinnedWref	string	The version-pinned wref for this target
target.name	string	The name segment of the wref
target.kind	string	One of thing, assertion, shape, collection
target.shape	string	Governing shape name for a shaped target; omitted for a shape target
target.shapeName	string	Governing shape name for a shaped thing; for a shape target, the target shape’s own name
target.version	integer	Current version number
target.data	object	Shape-defined payload; for a shape target, the shape definition
target.active	boolean	false when the target has been retracted
target.aboutWref	string	Present on assertions — the wref of the shape or shaped thing this assertion is about
target.committerWref	string	Optional committer the writer declared via --committer — present only when the originating write recorded one
target.createdBy	string	Optional. Wref of the authenticated identity that authored the first version of this target (immutable creator attribution); omitted when the creator cannot be resolved
target.revisedBy	string	Optional. Wref of the authenticated identity that authored the current version (distinct from the optional committerWref label); omitted when the current-version author cannot be resolved
target.metadata	object	Stable durable identifier and creation timestamps (see metadata fields in the GET /head field table)

Each item in assertions includes the same fields as items returned by GET /head (see the field reference in GET /head), plus a children array — nested assertions about that assertion, populated when a higher depth is requested and [] otherwise. When includeRetracted=true is combined with depth > 1, retracted assertions appear in children arrays at every nesting level, not just at the top level.

The example below uses CongressTrade + CongressTradeSecurity because the relationship assertion is about an Arc from the trade to its resolved security. Pass resolveCollections=true to include that relationship in the /about response.

{
  "target": {
    "wref": "CongressTrade/20034954/bd598743649e738e-2",
    "pinnedWref": "CongressTrade/20034954/bd598743649e738e-2@v1",
    "name": "20034954/bd598743649e738e-2",
    "kind": "thing",
    "shapeName": "CongressTrade",
    "version": 1,
    "active": true,
    "data": { "ticker": "CSCO", "filing_doc_id": "20034954", "transaction_type": "sale_partial" },
    "metadata": {
      "durableId": "040SXA5RYM7Q4QXAGM8N6MXYVH5G37TDS2P16YQAG6D6M3VKT6YE8ZCW52H0",
      "createdOn": 1783716424678,
      "revisedOn": 1783716424678
    }
  },
  "assertions": [
    {
      "wref": "CongressTradeSecurity/20034954/bd598743649e738e-2--0000858877",
      "name": "20034954/bd598743649e738e-2--0000858877",
      "kind": "assertion",
      "active": true,
      "shapeName": "CongressTradeSecurity",
      "version": 1,
      "createdAt": 1783803885129,
      "data": { "cik10": "0000858877", "ticker_raw": "CSCO", "resolver_confidence": 1 },
      "aboutWref": "Arc/congress-trade-20034954-bd598743649e738e-2-security-listing-0000858877@v1",
      "children": [],
      "metadata": {
        "durableId": "040SXA5RYM7Q4QXAGM8N6MXYVH5G37TJZWVKEZ7MHK5HJCWWDJ98DBEKFQYG",
        "createdOn": 1783803885129,
        "revisedOn": 1783803885129
      }
    }
  ],
  "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, including relationship assertions on its collections
curl "https://api.warmhub.ai/api/repos/warmhub-data/us.congress.trades/about/CongressTrade%2F20034954%2Fbd598743649e738e-2?resolveCollections=true"

# Only CongressTradeSecurity-shape assertions, including retracted
curl "https://api.warmhub.ai/api/repos/warmhub-data/us.congress.trades/about/CongressTrade%2F20034954%2Fbd598743649e738e-2?shape=CongressTradeSecurity&includeRetracted=true&resolveCollections=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

Each item in items includes the same fields as items returned by GET /head — see the field reference in GET /head for the full list. All timestamp fields are epoch-millisecond numbers.

{
  "items": [
    {
      "wref": "CongressTrade/20034954/bd598743649e738e-2",
      "name": "20034954/bd598743649e738e-2",
      "kind": "thing",
      "active": true,
      "shapeName": "CongressTrade",
      "version": 1,
      "createdAt": 1783716424678,
      "data": { "ticker": "CSCO", "amount_range": "$1,001 - $15,000", "transaction_type": "sale_partial" },
      "metadata": {
        "durableId": "040SXA5RYM7Q4QXAGM8N6MXYVH5G37TDS2P16YQAG6D6M3VKT6YE8ZCW52H0",
        "createdOn": 1783716424678,
        "revisedOn": 1783716424678
      }
    }
  ],
  "nextCursor": "whc1_eyJ2Ijox..."
}

Example

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

# Assertions about a specific thing
curl "https://api.warmhub.ai/api/repos/warmhub-data/us.congress.trades/query?about=CongressTrade%2F20034954%2Fbd598743649e738e-2&kind=assertion"