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
q | Matches part of a label or of a type name |
label | Matches part of a label |
slug | An exact type name, e.g. Publication: schemas some collection uses for that type |
schema_hash | An exact schema hash (bare hex). Returns that one schema as an object instead of a list, with usageCount, or 404 |
limit | Max results (default 50, max 100) |
offset | Pagination 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
version | A semver (v1.2.0), a version id (ulv3:…), or latest (the default) |
raw | true 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
200 | The schema already has this label: "status": "exists" |
400 | The label is empty or longer than 100 characters. |
401 / 403 | Not signed in, or a read-only key. |
404 | The 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.