Registry Relay API

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 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.

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.

CSV, XLSX, and Parquet are source decoders. Aggregate output supports JSON, CSV, and SDMX-JSON. CSV and XLSX input plus JSON aggregate output are stable for 1.0. Parquet input, CSV aggregate output, and SDMX-JSON aggregate output remain shipped but experimental and feature-frozen.

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.

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. The live OGC API Features, Records, and EDR adapters, SP DCI sync routes and standards-CEL mapping are experimental and feature-frozen. They are outside the 1.0 compatibility promise and excluded from the canonical release binary. Their source and all-feature tests remain available. Governed attribute release is stable and included in the canonical binary. Relay does not issue response credentials or host issuer DID documents.
Link-free Records metadata. Stable link-free OGC Records bodies under /metadata/ogc/records are portable metadata. They are separate from the experimental live adapter under /ogc/v1/records.
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. RS-OP-POSTURE defines the versioned posture document returned by GET /admin/v1/posture.
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.