Skip to content
Henceforth Docs

Fetch the API contract from a running server

Goal

Section titled “Goal”

Fetch the OpenAPI document of the routes a running Henceforth instance serves, and its metadata schema files, so a client generator or an agent can work against the exact contract that instance speaks — without a source checkout.

Prerequisites

Section titled “Prerequisites”
  • A running Henceforth server you can reach over HTTP.
  • No credentials needed: both routes below are public.

Routes

Section titled “Routes”
Method Path Returns
GET /.well-known/henceforth/openapi.json The full OpenAPI 3.1 document.
GET /.well-known/henceforth/schema/{type}.json One metadata schema document.

{type} is one of: field, object, module, relationship, seed, settings, validation_rule, screen. Each schema keeps the $id it was committed with — nothing is rewritten for serving.

Steps

Section titled “Steps”

1. Fetch the OpenAPI document

Section titled “1. Fetch the OpenAPI document”
Terminal window
curl https://your-server/.well-known/henceforth/openapi.json

The document describes the binary that serves it: every route this instance mounts, its parameters, and its request/response shapes. A server built with the default features serves exactly the document the source tree commits at docs/openapi/henceforth.openapi.json. A server built with optional features serves its own, larger document: one built with HFX support, for example, adds the /v1/hfx/* routes.

2. Fetch a metadata schema

Section titled “2. Fetch a metadata schema”
Terminal window
curl https://your-server/.well-known/henceforth/schema/object.json

Swap object for any of the eight types above. A request for an unknown type returns 404.

3. Feed the document to a client generator

Section titled “3. Feed the document to a client generator”

Point any OpenAPI 3.1 client generator at the fetched document to produce a typed client for that instance, rather than hand-rolling requests. The generated client will reflect the write convention exactly as documented — see the next step.

4. Read the metadata write path template

Section titled “4. Read the metadata write path template”

Every metadata write operation documents its path as /v1/metadata@{branchId}/... — metadata@main writes to main in instant mode and requires the admin.metadata.apply permission in addition to the operation’s own permission, and any other id writes to that cart branch. Look up branchId in the fetched OpenAPI document’s parameter descriptions for the exact semantics before generating write requests.

Verification

Section titled “Verification”

Confirm your server’s contract matches its own source tree at the commit it was built from:

Terminal window
curl https://your-server/.well-known/henceforth/openapi.json \
  | diff - docs/openapi/henceforth.openapi.json

An empty diff means the instance is serving exactly what a checkout at that commit would generate. The same comparison works for each schema file against its docs/schema/*.schema.json counterpart.

Notes

Section titled “Notes”
  • Both routes serve the artifacts the binary was built with – not a live, request-time regeneration. Rebuilding the binary from a different commit changes what they return.
  • Every other route this server serves (/v1/data/..., /v1/metadata/..., /v1/metadata@{branchId}/..., and so on) carries the global /v1/ prefix. /.well-known/... routes, these two included, are exempt by design – well-known URIs are unversioned by RFC 8615 – and stay at the paths shown above.

See also

Section titled “See also”