Queries

Query endpoints read data from a repository without modifying it. Public repositories can be queried without authentication. Private repositories require a valid Bearer token — anonymous requests receive a 404 response.

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

`GET /head`

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

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, returns all items without cursor pagination.
`cursor`	string	No	Opaque pagination cursor from a previous `nextCursor` response. Requires `limit`.

Response `200`

{
  "items": [
    {
      "wref": "Sensor/temp-1",
      "name": "temp-1",
      "kind": "thing",
      "shapeName": "Sensor",
      "version": 3,
      "data": {
        "location": "Building A",
        "type": "temperature"
      }
    }
  ],
  "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.

Example

# All things in the Sensor shape
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/head?shape=Sensor"

# All shapes in the repository
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/head?kind=shape"

# Paginate through results
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/head?shape=Sensor&limit=20&cursor=whc1_eyJ2Ijox..."

`GET /log`

Return the commit log. Commits are returned in reverse chronological order (newest first).

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum commits to return (max 500)
`cursor`	string	No	Opaque pagination cursor from a previous `nextCursor` response
`author`	string	No	Filter by author name
`since`	ISO 8601	No	Commits after this timestamp
`until`	ISO 8601	No	Commits before this timestamp

Response `200`

{
  "items": [
    {
      "commitId": "a1b2c3d4e5f6a7b8",
      "author": "sensor-agent",
      "message": "Add temperature sensor",
      "operationCount": 1,
      "addCount": 1,
      "createdAt": 1741132800000
    }
  ],
  "nextCursor": "whc1_eyJ2Ijox..."
}

Example

# Last 10 commits
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/log?limit=10"

# Commits by a specific author since a date
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/log?author=sensor-agent&since=2026-03-01T00:00:00Z"

`GET /history`

Return the version history for a thing, shape, or set of assertions.

Query Parameters

Parameter	Type	Required	Description
`wref`	string	No*	Thing wref (URL-encoded)
`shape`	string	No*	Filter by shape name
`about`	string	No*	Filter assertions about a target wref
`resolveCollections`	boolean	No	When `about` is set, also include assertions about collections containing the target (default `false`)
`includeInactive`	boolean	No	Allow resolving deactivated shape or about targets (does not filter results)
`limit`	integer	No	Maximum versions to return (max 500)
`cursor`	string	No	Opaque pagination cursor from a previous `nextCursor` response. Requires `limit`.

At least one of wref, shape, or about is required.

Response `200`

{
  "thing": {
    "wref": "Sensor/temp-1",
    "name": "temp-1",
    "kind": "thing",
    "shapeName": "Sensor"
  },
  "versions": [
    {
      "wref": "Sensor/temp-1",
      "thingName": "temp-1",
      "thingKind": "thing",
      "shapeName": "Sensor",
      "version": 1,
      "operation": "add",
      "data": { "location": "Building A", "type": "temperature" },
      "commitId": "e4f5a6b7c8d9e0f1",
      "commitAuthor": "sensor-agent",
      "commitTime": 1741132800000
    },
    {
      "wref": "Sensor/temp-1",
      "thingName": "temp-1",
      "thingKind": "thing",
      "shapeName": "Sensor",
      "version": 2,
      "operation": "revise",
      "data": { "location": "Building B", "type": "temperature" },
      "commitId": "a1b2c3d4e5f6a7b8",
      "commitAuthor": "sensor-agent",
      "commitTime": 1741219200000
    }
  ],
  "nextCursor": "whc1_eyJ2Ijox..."
}

When querying by shape or about without a specific wref, the thing field is omitted and the versions array contains entries from all matching things.

Example

# Version history for a specific thing
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/history?wref=Sensor%2Ftemp-1"

`GET /things/:wref`

Get a single thing by its wref, including its data payload.

Path Parameters

Parameter	Type	Description
`wref`	string	URL-encoded wref (e.g., `Sensor%2Ftemp-1`)

Query Parameters

Parameter	Type	Required	Description
`version`	integer	No	Specific version number. Defaults to the current version.

Response `200`

{
  "wref": "Sensor/temp-1",
  "name": "temp-1",
  "kind": "thing",
  "active": true,
  "shapeName": "Sensor",
  "version": 3,
  "operation": "revise",
  "data": {
    "location": "Building A",
    "type": "temperature",
    "lastReading": 72.5
  }
}

Errors

Code	Status	Description
`NOT_FOUND`	404	No thing found with this wref
`VALIDATION_ERROR`	400	Missing or invalid wref

Example

# Current version
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/things/Sensor%2Ftemp-1"

# Specific version
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/things/Sensor%2Ftemp-1?version=2"

`GET /about/:wref`

Get a thing and all assertions about it.

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)
`includeInactive`	boolean	No	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)
`cursor`	string	No	Opaque pagination cursor from a previous `nextCursor` response

Response `200`

{
  "target": {
    "wref": "Sensor/temp-1",
    "name": "temp-1",
    "kind": "thing",
    "shapeName": "Sensor",
    "version": 3
  },
  "assertions": [
    {
      "wref": "Reading/temp-1-v1",
      "name": "temp-1-v1",
      "kind": "assertion",
      "shapeName": "Reading",
      "version": 1,
      "data": {
        "value": 72.5,
        "timestamp": "2026-03-01T12:00:00Z"
      },
      "about": "temp-1@v3",
      "children": []
    }
  ],
  "nextCursor": "whc1_eyJ2Ijox..."
}

Errors

Code	Status	Description
`WREF_UNRESOLVABLE`	404	Cannot resolve the target wref
`VALIDATION_ERROR`	400	Missing or invalid wref

Example

# All assertions about a thing
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/about/Sensor%2Ftemp-1"

# Only Reading-shape assertions, including retracted
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/about/Sensor%2Ftemp-1?shape=Reading&includeInactive=true"

`GET /query`

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

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`)
`includeInactive`	boolean	No	Include deactivated/retracted items (default `false`)
`limit`	integer	No	Maximum items to return (max 500)
`cursor`	string	No	Opaque pagination cursor from a previous `nextCursor` response

Response `200`

{
  "items": [
    {
      "wref": "Sensor/temp-1",
      "name": "temp-1",
      "kind": "thing",
      "active": true,
      "shapeName": "Sensor",
      "version": 3,
      "data": { "location": "Building A" }
    }
  ],
  "nextCursor": "whc1_eyJ2Ijox..."
}

Example

# All things in the Sensor shape
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/query?shape=Sensor&kind=thing"

# Assertions about a specific thing
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/query?about=Sensor%2Ftemp-1&kind=assertion"

`GET /count`

Return the count of items matching the specified filters, without returning the items themselves. Useful for dashboards, progress tracking, and size checks before paginated fetches.

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)
`about`	string	No	Filter assertions by target wref
`includeInactive`	boolean	No	Include deactivated/retracted items (default `false`)
`resolveCollections`	boolean	No	When `about` is set, also include assertions about collections containing the target (default `false`)

Response `200`

{
  "count": 42
}

Example

# Count all things in a shape
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/count?shape=Sensor"

# Count assertions about a thing
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/count?about=Sensor%2Ftemp-1&kind=assertion"

# Count with glob pattern
curl "https://api.warmhub.ai/api/repos/myorg/myrepo/count?match=Sensor%2Fbuilding-a%2F*"

`GET /resolve/:wref`

Resolve a wref to its thing, returning the full data payload.

Path Parameters

Parameter	Type	Description
`wref`	string	URL-encoded wref to resolve

Response `200`

{
  "wref": "Sensor/temp-1",
  "name": "temp-1",
  "kind": "thing",
  "active": true,
  "shapeName": "Sensor",
  "version": 3,
  "data": {
    "location": "Building A",
    "type": "temperature"
  }
}

Errors

Code	Status	Description
`WREF_UNRESOLVABLE`	404	Cannot resolve this wref
`VALIDATION_ERROR`	400	Missing or invalid wref

Example

curl "https://api.warmhub.ai/api/repos/myorg/myrepo/resolve/Sensor%2Ftemp-1"

Queries

GET /head

Query Parameters

Response 200

Example

GET /log

Query Parameters

Response 200

Example

GET /history

Query Parameters

Response 200

Example

GET /things/:wref

Path Parameters

Query Parameters

Response 200

Errors

Example

GET /about/:wref

Path Parameters

Query Parameters

Response 200

Errors

Example

GET /query

Query Parameters

Response 200

Example

GET /count

Query Parameters

Response 200

Example

GET /resolve/:wref

Path Parameters

Response 200

Errors

Example

`GET /head`

Response `200`

`GET /log`

Response `200`

`GET /history`

Response `200`

`GET /things/:wref`

Response `200`

`GET /about/:wref`

Response `200`

`GET /query`

Response `200`

`GET /count`

Response `200`

`GET /resolve/:wref`

Response `200`