# Registry API

The Railiance Fabric registry is a small HTTP API over accepted Fabric graph
snapshots, discovery evidence, reset archives, and supporting inventory.
Legacy repo-local declarations can still produce snapshots, but they are
evidence for the graph rather than the long-term authority for external
deployment, ownership, tenant, or utility relations.

## Health And Status

```text
GET /health
GET /status
```

`/health` is intentionally tiny. `/status` includes database path, table counts,
and the latest accepted snapshot per repository.

## Repository Snapshots

```text
POST /repositories
GET  /repositories
GET  /repositories/{repo_slug}
GET  /repositories/{repo_slug}/inventory
POST /repositories/{repo_slug}/snapshots
GET  /repositories/{repo_slug}/snapshots
GET  /repositories/{repo_slug}/snapshots/latest
GET  /repositories/{repo_slug}/snapshots/diff
```

Snapshot ingestion accepts a `FabricGraphExport` under `graph` plus `commit`
and optional `generated_at`. The registry accepts both legacy
`railiance.fabric/v1alpha1` graph exports and the financial
`railiance.fabric/v1alpha2` / `financial-fabric-v1` export contract.

## Discovery Snapshots

```text
POST /repositories/{repo_slug}/discovery-snapshots
GET  /repositories/{repo_slug}/discovery-snapshots
GET  /repositories/{repo_slug}/discovery-snapshots/latest
GET  /repositories/{repo_slug}/discovery-snapshots/diff
GET  /repositories/{repo_slug}/discovery-snapshots/{snapshot_id}
POST /repositories/{repo_slug}/discovery-snapshots/{snapshot_id}/accept
```

Discovery ingestion accepts a `FabricDiscoverySnapshot`. Snapshots are stored by
repo, commit, and scan profile for dry-run review. Discovery diffs include
candidate additions, removals, changes, confidence changes, reconciliation
conflicts, and scoped retirements.

Acceptance projects only explicitly accepted discovery candidates into a normal
`FabricGraphExport` snapshot. Existing graph nodes are preserved, so repo-owned
declarations are not overwritten by discovery output. Projected nodes carry
discovery provenance, review state, confidence, and source anchors in their
attributes; graph explorer exports surface that metadata.

CLI helpers:

```bash
railiance-fabric registry ingest-discovery discovery.json \
  --repo-slug railiance-fabric

railiance-fabric registry accept-discovery railiance-fabric 12 \
  --accepted-key discovery:railiance-fabric:service-declaration:example
```

## Graph Queries

```text
GET /graph/nodes
GET /graph/nodes/{graph_id}
GET /graph/providers?capability_type=runtime-secrets
GET /graph/consumers?target=railiance-platform.openbao.kv-v2
GET /graph/unresolved
GET /graph/blast-radius?interface_id=openbao-kv-v2-mount
GET /graph/dependency-path?service_id=flex-auth.api
GET /search?q=jsonschema
```

## Artifacts And Libraries

```text
POST /artifacts
GET  /artifacts
GET  /artifacts/{artifact_id}
GET  /libraries
GET  /libraries/{library_id}
GET  /repositories/{repo_slug}/libraries
POST /repositories/{repo_slug}/libraries/cyclonedx
```

CycloneDX ingestion replaces the repo's current library inventory with the
components and services in the submitted SBOM.

## Exports

```text
GET /exports/state-hub
GET /exports/backstage
GET /exports/xregistry
GET /exports/libraries/xregistry
GET /ui/graph-explorer
GET /exports/graph-explorer/manifest
GET /exports/graph-explorer
GET /exports/reset-archive
```

`GET /exports/state-hub` currently serves the accepted combined graph for the
State Hub read model. During the financial reset, keep using the legacy shape
for existing State Hub views until `STATE-WP-0051` materializes v1alpha2
fields. Use `railiance-fabric export --format financial` and
`examples/exports/financial-fabric-v1.json` as the vNext contract references.

## Guarded Reset

```text
POST /admin/reset-graph-data
```

The reset endpoint requires `confirm`,
`reason`, and `archive_sha256`. `confirm` must be
`RESET-RAILIANCE-FABRIC-GRAPH-DATA`. Operators should prefer the CLI wrapper
documented in `docs/registry-reset-operations.md`, because it exports the
archive and computes the checksum before calling the destructive endpoint.