genroc speaks one HTTP API and everything else is a client of it — genctl, the UI, and whatever you write. The pages below list every endpoint, grouped by what it acts on.

Everything is served under /api, except the readiness probe at /healthz — a probe must not move when the API namespace does.

The document

The endpoint list is generated from the server’s own action registry, so it cannot drift from what is served. This site publishes it at /openapi.json, and a running server serves the same document at /public/openapi.json with a browsable UI at /public/docs.

A client generator takes it as-is — the base path is declared once in servers, so generated calls prepend /api and the documented paths stay the ones the server routes.

To browse it as an API explorer rather than as JSON, there is a Swagger UI here. It is read-only: genroc sends no CORS headers, so a request issued from this domain is blocked by the browser before it reaches anything. Your own server serves the same explorer at /public/docs, same-origin, with Try it out working.

There is also a per-process document, with that process’s input_schema patched into the start-instance body:

curl localhost:8448/api/definitions/welcome-user/openapi.json

Its browsable form is at /api/definitions/{name}/docs.

Authentication

genroc accepts exactly two credentials, both on Authorization: Bearer:

credential	who holds it	genroc’s role
an opaque genroc_sk_*	machines — CI, workers, apps, genctl	issues it, and verifies it
a signed JWT	people, through genroc-ui	verifies only — never issues, never refreshes

Nothing else is an identity: no trusted headers, no cookies, no client certificates. A deployment configures genroc to accept its identity provider’s tokens, and that configuration is the whole integration.

The default is -auth none, which handles no Authorization at all and leaves every endpoint open. That is fine on a laptop and nowhere else — PUT /definitions is arbitrary code execution on the server — so genroc warns at startup when it is also bound beyond loopback.

Permissions

Each endpoint page states what its endpoint needs. Any one of the listed permissions admits the call, and admin always does.

permission	covers
worker	the inbound zone — claim, renew, release, resolve, signal — and fetching an object
read	every GET except /tokens, plus the requests that write nothing (validate, compat, channel status)
operate	acting on runs: start, pause, resume, cancel, retry
deploy	changing what runs: definitions, channels, upgrade
admin	tokens (including listing them), /tick, and anything that declares nothing

/healthz needs no token.

They are a flat set, not a hierarchy — a role maps to a list. upgrade sits under deploy rather than operate because it changes which version an instance executes.