API reference

Every route of the OpenRegs serving API, generated from the route table in tooling/openregs/serve/routes.py at f3a2d10 by tooling/ci/dump_openapi.py — never transcribed, so a route cannot change without this page changing with it.

The document is served beside these pages as openapi.json: OpenAPI 3.1.0, describing API version 0.1.0, the same bytes core emitted at that commit, for a client generator to read.

Serving is a projection of a release artifact and nothing else: an instance reads the released corpus, graph and chunk index, and never a canon, a git commit or the network. An answer given inside a consumer’s own network is therefore the answer the hosted deployment gives, byte for byte, and both carry citations into the canonical text.

Every response is stamped. verification says what was checked before this release was served, and disclaimer carries the project’s non-advice statement beside the release tag — so a document read long after the request still says which corpus it came from and that it was not advice.

Every failure has one shape: an error object of code, message and request_id, whether it came from the application, from the policy layer in front of it, or from an exception nobody expected.

Two protocols, one implementation. The same service answers the Model Context Protocol, where it exposes 5 tools; 4 of them have a REST route here — search_regulation, get_unit, get_atom, list_obligations — and each operation names its twin in x-openregs-mcp-tool. The payload is one document produced once, not two documents compared afterwards.

diff_releases has no REST route, and that is a decision rather than a gap. A served instance can answer exactly one range: the manifest its own release ships, from the tag that manifest names. Every other pair of tags is a refusal, so a REST route would be an operation whose domain is a single value per deployment, and a generated client would carry a method it can call correctly once. That is not the shape of the gap, though — it is the symptom. A diff manifest is a release artifact, and a consumer acting on a change has to verify the release the change is in before acting: openregs pull checks the signature chain, the digests and the provenance, and an HTTP hop from one instance checks none of them. Serving the manifest over REST would offer the evidence-shaped thing on the notification-shaped path, which is precisely the split https://docs.openregs.io/overview/ keeps deliberate. The three readers of the manifest already read the artifact: openregs diff aggregates a multi-release range one published tag at a time, openregs impact intersects one with a control mapping, and openregs feed pushes entries and expects the handler to pull. The tool stays on MCP because an agent holding a session is asking about the release in that session and has the answer in front of it; a client library integrating against a deployment is not, and would be better served by the release than by this.

A method a path does not declare is refused with 405 method_not_allowed, in that same shape. It is listed under no operation here because an operation is a path and a method, and no method answers 405 to itself.

CORS. A preflight OPTIONS is answered on every path when the deployment allows the calling origin. It belongs to no route and so appears under none of them.

The engine is Apache-2.0; the corpus an instance serves is CC-BY-4.0.

Servers

Server
http://127.0.0.1:8080	Where openregs serve binds unless it is told otherwise: loopback, because a server that binds every interface by default is a server somebody deploys by accident. A hosted instance answers on its own name.

Authentication

Scheme
bearerAuth (http bearer)	Authorization: Bearer <token>. The deployment configuration lists the credentials it accepts as sha256 digests and gives each one its own per-minute limit; whether a request with no token is answered at all is stated in that file and never inferred.

Each operation names which of these it accepts, and whether it answers a request that presents none.

Operations

Running the process: liveness, readiness, and the metrics scrape.

Operation
GET /healthz	Whether this process is alive
GET /metrics	The metric registry, in the Prometheus text exposition format
GET /readyz	Whether this instance may be sent traffic

Regulation

Reading the pinned release. Every answer carries citations.

Operation
POST /v1/answer	Answer a question over the pinned release, with citations
POST /v1/atom	One obligation atom’s own record, by id, as of a date
POST /v1/obligations	Every duty binding one entity profile on one date
POST /v1/unit	One unit’s text and metadata, by eId, as of a date

Schemas

The 14 shapes these operations read and return are on their own page: Schemas.