Records and schemas API

These endpoints find the schemas collections use, and label them. Looking records up by hash across collections (a record’s provenance, where it first appeared, or fetching records by hash in a batch) is not available yet: read records through their collection with the Versions API.

Visibility

Every answer is limited to what the caller can read: public collections, plus the collections of the caller’s own organizations. A schema the caller can’t read is treated as not existing, and counts include only what the caller can see. The read endpoints work anonymously.


GET /api/schemas

No auth required

Search the schemas in use, newest first. A schema’s id is its hash: SHA-256 of its canonical JSON, as bare hex.

Query parameters

qMatches part of a label or of a type name
labelMatches part of a label
slugAn exact type name, e.g. Publication: schemas some collection uses for that type
schema_hashAn exact schema hash (bare hex). Returns that one schema as an object instead of a list, with usageCount, or 404
limitMax results (default 50, max 100)
offsetPagination offset

Schema bodies are not searched: q looks only at labels and type names.

Response 200

[
  {
    "id": "b41c07...",
    "schemaHash": "b41c07...",
    "schema": { "type": "object", "properties": { "title": { "type": "string" } } },
    "createdAt": "2026-01-15T00:00:00.000Z",
    "labels": ["scholarly-publication"]
  }
]

With schema_hash, usageCount is the number of collections the caller can read that have used the schema in any version:

{
  "id": "b41c07...",
  "schemaHash": "b41c07...",
  "schema": { "type": "object", "properties": { "title": { "type": "string" } } },
  "createdAt": "2026-01-15T00:00:00.000Z",
  "labels": ["scholarly-publication"],
  "usageCount": 3
}

GET /api/schemas/:id

No auth required

One schema, by hash, with its labels and where it is used now. usage lists up to 50 types, in the collections the caller can read, whose latest version uses this schema; semver is that collection’s latest version. Here each label comes with the time it was added. Returns 404 when the caller can’t see the schema.

Response 200

{
  "id": "b41c07...",
  "schemaHash": "b41c07...",
  "schema": { "type": "object", "properties": { "title": { "type": "string" } } },
  "createdAt": "2026-01-15T00:00:00.000Z",
  "labels": [
    { "label": "scholarly-publication", "createdAt": "2026-03-01T00:00:00.000Z" }
  ],
  "usage": [
    { "slug": "Publication", "semver": "v3.2.0", "collection": "kf/archive" }
  ]
}

GET /api/collections/:owner/:slug/schemas

No auth for public collections

The schema of each type in a version. Labels are added to each schema as x-underlay-labels when it has any; pass raw=true for the schemas exactly as pushed.

Query parameters

versionA semver (v1.2.0), a version id (ulv3:…), or latest (the default)
rawtrue leaves out x-underlay-labels

Response 200

{
  "version": "v3.2.0",
  "semver": "v3.2.0",
  "schemas": [
    {
      "slug": "Publication",
      "schemaId": "b41c07...",
      "schemaHash": "b41c07...",
      "schema": {
        "type": "object",
        "properties": { "title": { "type": "string" } },
        "x-underlay-labels": ["scholarly-publication"]
      }
    }
  ]
}

Returns 404 when the collection or version doesn’t exist, or the collection has no versions.


POST /api/schemas/:id/labels

Auth: signed in, or a write or admin API key

Add a label to a schema the caller can see, so others can find it. Body: {"label": "…"}, at most 100 characters after trimming spaces. Adding a label the schema already has is not an error.

Example

curl -X POST https://www.underlay.org/api/schemas/b41c07.../labels \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "scholarly-publication"}'

Response 201

{
  "status": "created",
  "schemaId": "b41c07...",
  "label": "scholarly-publication"
}

Errors

200The schema already has this label: "status": "exists"
400The label is empty or longer than 100 characters.
401 / 403Not signed in, or a read-only key.
404The schema doesn’t exist or the caller can’t see it.

DELETE /api/schemas/:id/labels/:label

Auth: Underlay stewards only (session, or a write or admin key)

Remove a label from a schema. A label is shared by every collection that uses the schema, so only Underlay’s stewards (Knowledge Futures administrators) can remove one, signed in or with a personal write or admin key. Anyone else is 403; a read key, or a key confined to collections or held by an organization, is 401. Returns {"ok": true}, also when the schema didn’t have the label.