> For the complete documentation index, see [llms.txt](https://docs.startrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/schema-registry.md).

# Schema registry

The four public schema-registry routes — search, record by CID, document by CID, record by name and version.

Public, no headers required. Base path: `<base_url>/port/api/v1/schema-registry`.

| Route                                                               | Returns                                                |
| ------------------------------------------------------------------- | ------------------------------------------------------ |
| <mark style="color:blue;">`GET`</mark> `/search?query=&page=&size=` | Public published records, paginated, no documents      |
| <mark style="color:blue;">`GET`</mark> `/cid/{cid}`                 | One published record with its schema document          |
| <mark style="color:blue;">`GET`</mark> `/cid/{cid}/document`        | The schema document only, with immutable cache headers |
| <mark style="color:blue;">`GET`</mark> `/name/{name}?version=`      | One published record of a lineage, no document         |

Registration, review and publication are not on these routes; Startbahn does them for you.

## Record shape

```json
{
  "cid": "bafkreigxv3lhvqmfz5n6g2xzpt4ql3a4ql7ekg7kza6iz5s4ms2nrv4d4u",
  "schemaUri": "ipfs://bafkreigxv3lhvqmfz5n6g2xzpt4ql3a4ql7ekg7kza6iz5s4ms2nrv4d4u",
  "name": "ingot-registry-record",
  "title": "Ingot Registry Record",
  "description": "One record per bar or ingot in custody.",
  "imageUrl": null,
  "version": "0.3",
  "visibility": "public",
  "dialect": "2020-12",
  "isLatest": true,
  "status": "published",
  "submittedAt": "2026-10-20T08:12:00.000Z",
  "reviewedAt": "2026-10-21T09:00:00.000Z",
  "reviewNote": null,
  "createdAt": "2026-10-20T08:11:58.000Z",
  "updatedAt": "2026-10-21T09:00:00.000Z",
  "schemaDocument": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "…": "…" }
}
```

| Field                                     | Description                                              |
| ----------------------------------------- | -------------------------------------------------------- |
| `cid`                                     | CIDv1 of the canonical schema document                   |
| `schemaUri`                               | `ipfs://<cid>` — the value to use as `metadata.$schema`  |
| `name`                                    | Lineage slug, the `<name>` of the name form of `$schema` |
| `title`, `description`, `imageUrl`        | Display fields                                           |
| `version`                                 | Version label, the `<version>` of the name form          |
| `visibility`                              | `public` or `private`                                    |
| `dialect`                                 | `draft-07` or `2020-12`                                  |
| `isLatest`                                | `true` on the lineage's latest published release         |
| `status`                                  | Only `published` records are served here                 |
| `submittedAt`, `reviewedAt`, `reviewNote` | Review trail; `null` when not applicable                 |
| `schemaDocument`                          | The JSON Schema. Present on `/cid/{cid}` only            |

## `GET /search`

| Query   | Default | Rule                                                                                                     |
| ------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `query` | —       | Substring match (case per database collation) on `name`, `title`, `description`. At most 2000 characters |
| `page`  | `1`     | ≥ 1                                                                                                      |
| `size`  | `50`    | 1 … 100                                                                                                  |

Only **public, published** records. Ordered latest releases first, then newest first.

```json
{ "results": [ { "cid": "…", "name": "ingot-registry-record", "version": "0.3", "isLatest": true, "…": "…" } ], "count": 1, "page": 1, "size": 50 }
```

| Status | Message                                                                                                                      | When                          |
| ------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `400`  | `size must be at least 1` / `size must not exceed 100` / `page must be at least 1` / `query must not exceed 2000 characters` | Out-of-range query parameters |

## `GET /cid/{cid}`

The record plus `schemaDocument`, read from the IPFS CDN. Resolves **private** schemas too: holding the CID is the permission. `Cache-Control: no-cache`.

| Status | Message            | When                                                 |
| ------ | ------------------ | ---------------------------------------------------- |
| `404`  | `schema not found` | Not a CID, no record, or the record is not published |

## `GET /cid/{cid}/document`

The schema document alone, `Content-Type: application/schema+json`, `Cache-Control: public, max-age=31536000, immutable`, `ETag: "<cid>"`. For validators and schema browsers that resolve a `$schema` CID without an IPFS gateway.

| Status | Message                     | When                                                                        |
| ------ | --------------------------- | --------------------------------------------------------------------------- |
| `404`  | `schema not found`          | Not a CID, no record, or not published                                      |
| `404`  | `schema document not found` | The record exists but the document could not be read from the CDN right now |

## `GET /name/{name}?version=`

| Query                         | Rule                                                                                                      |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| `version` omitted or `latest` | The lineage's latest published release (`isLatest`, else the highest version)                             |
| `version=<label>`             | The published release with that version, compared by value (`1.0.0` matches a record registered as `1.0`) |

Published records only, whatever their visibility. No `schemaDocument` — read it by CID. `Cache-Control: no-cache`. This is the lookup behind the name forms of `$schema`.

```
GET <base_url>/port/api/v1/schema-registry/name/ingot-registry-record?version=latest
```

| Status | Message            | When                                                         |
| ------ | ------------------ | ------------------------------------------------------------ |
| `404`  | `schema not found` | No published release of that name, or none with that version |

## Documents without `title` or `name`

`name`, `title` and `version` are fields of the registry record, given at registration (`name` a lowercase slug of 3 to 64 characters, `title` up to 256); they are not read from the schema document, which may omit JSON Schema `title`. Metadata on the schema is constrained only by what the document declares: a schema that does not require a `name` field yields SRRs without one, and nothing in the API adds one.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/schema-registry.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
