Hiveram

HTTP API

A machine-readable contract, and a quickstart that runs a real lifecycle.

Anything the ledger holds is reachable over an authenticated HTTP API. It ships an OpenAPI 3.1 contract served from the same bytes committed with the server — so the contract cannot drift from the running service between releases.

The contract

Served at an authenticated GET /v1/openapi.yaml, versioned with the server release. It covers 116 path items across 146 literal /api/v1 registrations.

The contract is explicit about how far its guarantees go, because that boundary is the useful part:

Contract facts, including which POST operations are read-only, are in the OpenAPI contract facts.

Retry identity

Agents retry. The API is explicit about which operations carry a deduplication key and which do not, so an integration can tell a safe retry from a duplicate write.

Notes require an idempotency key. Creates accept a caller key and otherwise derive a request fingerprint. Identity mutations carry an operation ID. Claim, update or close, add relationship, link commit, and blob writes take no caller-provided deduplication key — stated plainly so you design around it rather than discovering it in production.

Python quickstart

A dependency-free example for Python 3.10 or newer. Standard library only — there is no package to install.

It performs one complete authenticated lifecycle using two distinct write credentials:

1. the agent creates a keyed work order, claims it, moves it to in_progress, and appends keyed evidence;
2. a separately authenticated reviewer closes the no-code work order;
3. the reviewer reads back the notes, the history, and the exact note-idempotency binding.

Two credentials, not one, because the closure gate compares the authenticated reviewer key against the recorded executor. Changing the actor field in JSON cannot disguise a self-close — the same rule the ledger enforces everywhere, visible here in the smallest runnable form.

The example refuses remote plaintext HTTP, rejects URL userinfo and redirects before forwarding a credential, and redacts secrets from every diagnostic. A quickstart that teaches a careless pattern is worse than no quickstart.

Environment setup and the runnable files: Python HTTP API quickstart.