Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/llms.txt
Full corpus: https://docs.registrystack.org/llms-full.txt

# Registry Relay API

> Narrative context for the Registry Relay OpenAPI reference: what the API surface is, how authentication works, and what the specification does not cover.

[Open the Registry Relay API operations](../relay/)

The generated API reference linked above is the **authoritative route reference**. It is built from
Registry Relay's OpenAPI document, synced from the
[`registry-relay`](https://github.com/registrystack/registry-stack) repository at the commit pinned in
`src/data/repo-docs.yaml`, so it tracks the real service rather than a hand-maintained copy. This
page carries only the context the specification does not: what the surface is, how authentication
works, and what is out of scope.

For exact routes, parameters, and schemas, read the generated API reference. For setup, scopes, and
integration detail, see the [Registry Relay product documentation](../../../products/registry-relay/).

## What the API is

Registry Relay implements the Protected Registry APIs pattern. It turns existing registry source
data, such as files, extracts, and database tables, into protected, read-only, domain-oriented
consultation APIs. Callers read configured entities, schemas, declared aggregates, catalog and
policy metadata, and evidence-offering descriptors. Relay never widens a caller's reach at request
time: the routes, datasets, and scopes a gateway exposes are fixed by its configuration.

## Authentication

A Relay instance runs exactly one auth mode (API key or OIDC/OAuth2), configured under `auth`.
Access is scope-based per dataset; liveness and readiness probes are unauthenticated.
For setup steps, scope strings, and credential configuration, see
[Client integration](../../../products/registry-relay/client-integration/).

## What the specification does not cover

- **Per-deployment shape.** Concrete dataset ids, entity names, aggregate ids, evidence-offering
  ids, and SP-DCI registry ids are runtime configuration, not contract data. To see what a specific
  gateway exposes, fetch `GET /openapi.json` or read `GET /metadata/catalog`. Runtime deployments
  gate OpenAPI by default unless `openapi_requires_auth` is disabled for demos or controlled tooling.
- **Purpose-header enforcement.** The shared `Data-Purpose` header parameter is optional in the
  baseline OpenAPI component because not every entity requires purpose capture. At runtime,
  `api.require_purpose_header: true` on an entity or aggregate source makes the header mandatory for
  that operation. Calls that omit it are rejected with `400 auth.purpose_required`.
- **Feature-gated surfaces.** OGC API Features, Records, and EDR adapters, and SP-DCI sync routes
  only mount when the gateway is built and configured with the matching Cargo feature.
  Relay does not issue response credentials or host issuer DID documents.
- **Admin routes.** Reload and metrics routes are mounted on a separate, optional admin listener,
  require `registry_relay:admin` for reload/config mutation, `registry_relay:metrics_read` for
  metrics, and `registry_relay:ops_read` for operational posture reads. They do not appear in the
  public OpenAPI document.
- **Evidence-offering discovery.** Relay publishes evidence-offering metadata at
  `GET /metadata/evidence-offerings` and `GET /metadata/evidence-offerings/{offering_id}`.
  These routes describe where to reach a Notary for verification; Relay does not execute the
  verification itself.
- **Read-only, no streaming.** Relay does not mutate source registry data. Sources are read as batch
  snapshots or table scans; there is no event-stream backend.