Skip to content

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.

Send an API token as a bearer token when calling the Manager remotely:

Terminal window
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.

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.

  • 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" reads dormant: true and is not placed until POST /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.
AreaPaths
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.