Manager API
The Manager API is the same interface used by the web UI and norsk-mgr
CLI. All finite operator resources and actions live under /api/v1. Health,
readiness, OpenAPI, Prometheus and the product reverse proxy are the deliberate
path exceptions.
The running service publishes the complete OpenAPI 3.1 document at
GET /api/openapi.json and GET /api/openapi.yaml. It is generated from the
Zod schemas that also validate requests, responses consumed by Manager clients,
and the TypeScript handler/client types.
Authentication
Section titled “Authentication”Send an API token as a bearer token when calling the Manager remotely:
curl -H "Authorization: Bearer $NORSK_MGR_TOKEN" \ "$NORSK_MGR_URL/api/v1/productions"A read token permits GET, HEAD and OPTIONS; a write token permits all
methods. The UI is authenticated by the front proxy. Local CLI calls can use
the loopback/proxy-secret path. Health and readiness are public; worker artifact
fetches use their own frozen capabilities. Shutdown and Prometheus remain
restricted to trusted local/proxy callers rather than ordinary bearer tokens.
Common shapes
Section titled “Common shapes”JSON errors have one envelope:
{ "status": "error", "code": "PRODUCTION_NOT_FOUND", "message": "Production 'morning-show' was not found", "details": {}}code is a stable uppercase identifier; details is present only when an
operation declares structured diagnostic data. Request validation failures use
the same envelope.
Paged collections accept limit and cursor and return the cursor in the
body:
{ "items": [], "nextCursor": null}Dates are ISO-8601 strings. SDK BigInts that cross the boundary, such as a
runtime’s currentHash, are decimal strings. Operator-authored resource names
are lowercase DNS-style labels unless the OpenAPI schema says the identifier is
opaque or provider-defined.
Resource model
Section titled “Resource model”- A production is named operator intent and owns its runtimes. Create or
replace the production; use runtime routes only to observe or invoke explicit
start, stop, activate and migrate actions. Raw runtime mutation is not public.
A runtime created with
startMode: "manual"readsdormant: trueand is not placed untilPOST /api/v1/runtimes/{id}/activate. - A product template has immutable revisions. Operator reads and edits use the latest revision with an expected-revision guard; a launch pins both the revision and artifact SHA so a later edit cannot change queued work.
- A pool embeds an ordered array of tiers. Replacing a pool replaces that array atomically. Tiers reference clouds and machine types rather than repeating them.
- A node includes its observed inventory. A local server is its registration and desired pool/spare state; deregistration removes that identity and its token, and reprovisioning creates it again.
- Placement and schedule are read models. A migration has its own lifecycle and retained history. Node services are currently an experimental read-only surface while their controller/selector model is finalized.
Main paths
Section titled “Main paths”| Area | Paths |
|---|---|
| Workloads | /api/v1/productions, /api/v1/runtimes, /api/v1/production-templates |
| Products | /api/v1/products, /api/v1/product-templates, /api/v1/workdir-assets |
| Capacity | /api/v1/pools, /api/v1/clouds, /api/v1/machine-types |
| Fleet | /api/v1/nodes, /api/v1/local-servers, /api/v1/hot-spares, /api/v1/template-images |
| Observation | /api/v1/placements/recent, /api/v1/schedule, /api/v1/migrations, /api/v1/alerts, /api/v1/audit, /api/v1/events |
| Administration | /api/v1/system/*, /api/v1/settings, /api/v1/tokens, /api/v1/proxy-users |
Treat the served OpenAPI document as the operation-level reference: it records
every method, request schema, success status, response media type, declared
error and security rule. /api/v1/internal/* is typed for the UI/development
tools but is not a public automation surface. /products/{name}/* is a reverse
proxy into a product, not part of the Manager contract.