Feed API reference

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

The document is served beside these pages as feed-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.

The outbound side of a release. When a release is built, its diff manifest says which obligation atoms were added, changed, removed or deprecated and whether each change was substantive or editorial. This service is how a downstream system learns that without watching a repository: it serves those changes as a JSON Feed and an RSS feed, and it POSTs the ones a subscription asked for to that subscription’s endpoint, signed and retried.

It is a different server from the serving API. That one answers questions over a pinned release on its own port and has its own description in openapi.json. This one has its own port, its own store and its own lifecycle. It touches the checkout it was started over in exactly two places — when a release is announced, and when a feed item’s link is followed back to that release’s diff manifest — and everything else it answers comes out of its own store. It reads no canon, no git history and nothing off the network.

It re-decides nothing. The changes, and their substantive-or-editorial classification, are copied out of the release’s own diff manifest verbatim. The two things this service adds — which entity types a change binds and which jurisdiction it belongs to — come from the release’s own corpus bundle and are resolved once, at publication, because they are what a subscription filters on.

No authentication, and that is a deployment decision rather than an oversight. Everything it serves is already public; the one thing it holds that is not — the subscription signing secrets — is in no response. It binds loopback unless told otherwise and is meant to sit behind whatever terminates TLS and authenticates. There is no bearer token, no rate limit and no 401 anywhere in this document.

Every refusal is {"error": "<sentence>"} — a message and no code to branch on, and no correlation header. That is a real difference from the serving API and is stated here rather than left to be discovered.

A method a path does not answer is 404, not 405. Dispatch resolves a path first and a verb second, so a path nothing declares and a verb no route on that path answers are one refusal. A verb the server implements no handler for at all — anything but GET, POST and DELETE — is the standard library’s 501 in HTML, which belongs to no operation and appears under none.

The webhook is the other half of this API. It is declared under webhooks: a request your endpoint receives rather than one you make, with the headers to verify it by. A signature proves who sent the payload, not what the law says — a handler’s second step is openregs pull, which verifies the release’s own signature chain before anything is used.

The engine is Apache-2.0; the corpus a release carries is CC-BY-4.0.

Servers

Server
http://127.0.0.1:8787	Where openregs feed serve binds unless it is told otherwise: loopback, because a service holding subscription secrets and authenticating nobody must not be reachable from off the machine by default. A deployment sets —host and —base-url, and the base URL is what the links inside the feeds are written against.

Feeds

Reading the published changes: the root document and the two feed formats.

Operation
GET /	What this service is, where its feeds are, and how a delivery is signed
GET /feed.json	The published atom changes as a JSON Feed, narrowed by the query string
GET /feed.xml	The same entries as RSS 2.0, for everything that already reads RSS

Deliveries

Announcing a release, what it owes, and the log of every attempt at handing it over.

Operation
GET /deliveries	What is owed, and what state each delivery is in
POST /deliveries/retry	The retry pass: attempt everything now due
GET /log	The service log: every attempt at every delivery
POST /publish	Announce a built release, and attempt every delivery it creates
GET /releases/{regime}/{tag}/diff.json	The release’s own diff manifest, byte for byte as it shipped

Subscriptions

Registering an endpoint to be told, and stopping.

Operation
GET /subscriptions	What is registered — never the secrets
POST /subscriptions	Register one webhook endpoint, its secret and the filter it wants
DELETE /subscriptions/{subscription_id}	Stop sending to one subscription

Schemas

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