Skip to content

Reference

API reference

Every route this product serves, its request and response shape, the closed error-code set, the SSE frame types, and every hard limit. Source of truth: CONTRACT.md. Where a shape isn't spelled out field-by-field in CONTRACT.md itself, it's taken from apps/web/src/lib/demo-estate.ts, whose own header comment states it is "shaped exactly like the matching orbit-api response in CONTRACT.md". Each section below names its provenance, so you can tell a contract-guaranteed field from a documented-by-example one.

Conventions

  • JSON only. Every request body and response body is JSON; a non-JSON request body gets 415 / unsupported_media_type.
  • Errors are one shape, everywhere: {"error":{"code":"...","message":"..."}}, with an HTTP status that always matches the code. See "Error codes" below.
  • Auth: Authorization: Bearer <token>, the service bearer, on every route except GET /healthz and GET /readyz. On orbit-api, a signed-in user rides on top of it as X-Orbit-Session, which every route needs except the short public list in "Identity" below: no or bad session is 401 unauthorized, a role without the route's permission 403 forbidden. See security.md and identity.md.
  • From the browser, every path below is called against web's own origin (e.g. https://your-host/api/v1/clusters), and web's server forwards it to orbit-api unchanged, attaching the bearer and copying the orbit_session cookie into X-Orbit-Session. There is no separate public hostname for orbit-api. If you're calling a service directly for debugging (for example the debug ports docker-compose.yml publishes), attach the bearer yourself; see install/docker-compose.md.
  • Compression: through web, a JSON answer of 1 KiB or more crosses with Content-Encoding: gzip when the request accepts it. An SSE stream never does, and curl without --compressed gets the same JSON plain. orbit-api itself answers plain.
  • Logs, not responses: every request gets one slog JSON line on stdout (method, path, status, duration), regardless of outcome. See operations.md.

Routes every backend service exposes

RouteReturnsAuth?Notes
GET /healthz200 {"status":"ok"}No (always exempt)Liveness. Never touches a dependency, so a slow nocturne cannot fail orbit-api's liveness check.
GET /readyz200 when dependencies answer, 503 otherwiseNo (always exempt)Readiness. orbit-api checks its source and reports nocturne in the body ("nocturne": "ok" or "unavailable: …") without failing on it: an optional assistant down must not take the API out of its Service. nocturne checks provider reachability (cached, never per-request). Readiness must be able to fail (Addendum v0.2).
GET /metricsPrometheus expositionN/A (separate listener)Bound to ORBIT_METRICS_ADDR / NOCTURNE_METRICS_ADDR (default :9090), not the API port. gzip when the scraper sends Accept-Encoding: gzip. Not reachable through web's proxy; not covered by the auth exemption list because it isn't on the listener that list applies to. See security.md.
GET /api/v1/version{"version","commit","builtAt","go"}YesRequires a valid credential like any other API-listener route; on orbit-api, a session too. The go key is kept for compatibility and names the Rust toolchain.

orbit-api

Base path /api/v1. Every route below requires the bearer and, unless it says "public", a session whose role holds the permission in its row (identity.md has the closed list). Every route is subject to the global 20s request timeout and 1 MiB body limit unless a narrower limit is given.

RoutePermissionReturns
GET /clustersestate.readCluster[]
GET /clusters/{id}estate.readCluster
GET /clusters/{id}/nodesestate.readNode[]
GET /clusters/{id}/workloadsestate.readWorkload[]; query: ?namespace=&kind=&q=
GET /clusters/{id}/eventsestate.readEvent[]; query: ?limit= (max 500, see Limits)
GET /clusters/{id}/componentstelemetry.query and estate.readComponent[]: SRE Orbit's own controllers, {component, kind, namespace, name, image, version, running?, ready, desired, nodes?, status, parked?, attention, restarts, memory:{used, request}, problem?:{key, value, retries?}, disk?:{usedBytes, capacityBytes, fullAt?}}; restarts and problem cover 24 h, problem counted on the row's own pods (see operations.md)
GET /clusters/{id}/alertsestate.readAlert[], with the acknowledgement fields below
GET /clusters/{id}/changesestate.read{since, changes: [{at, last?, kind, namespace, workload?, object, by?, user?, reason?, message?, changes?, count?, revision?, severity?, alertId?, outcome?, objects?, approx?, key}], counts, cut, dropped, deckHidden}, the change timeline, newest first, at most 500 rows with the oldest Warnings the first left out; counts is each kind before that cut, cut the rows it left out, dropped what full days in the window never kept for the namespace, approx a time a tick gave, objects how many objects a Warning run covers, deckHidden true without audit.read; query: ?namespace= (required), &workload=, &from=&to= (Unix ms, default the last 24 h). kind is rollout, scale, warning, alert or deck; by is the field manager or HPA, user the Deck user of a deck row; the deck rows need audit.read. since is when recording began on the cluster, 0 before. Cache-Control: no-store. See audit.md → "The change timeline"
GET /clusters/{id}/finopsestate.readFinOps
GET /clusters/{id}/recommendationsestate.readRecommendation[]
GET /query_rangetelemetry.queryQueryResult; query: ?cluster=&expr=&from=&to=&step=
POST /contactpublic202 {"status":"accepted","leadId":"lead_<16 hex>"}, answered only once the lead is stored under ORBIT_DATA_DIR/leads (a failed write is 500, and nothing is accepted), then optionally POSTed to ORBIT_CONTACT_WEBHOOK_URL in the background (Addendum v0.7), for sales lead capture. Body fields: name (required), email (required, a parseable address), company, message (optional, ≤4000 chars), clusters (one of 1-5 6-20 21-100 100+), series (one of lt1m 1m-10m 10m-100m gt100m), locale, source. Unknown fields are refused with 400. The answer never echoes the payload, and a tripped honeypot gets the same answer as a real lead.
GET /leadsusers.manage{leads: [{id, ts, name, email, company, clusters, series, message, locale, source, ip}]}, newest first; ?format=csv downloads the same as a spreadsheet, formula-leading cells defused
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/logslogs.readtext/plain, or text/event-stream with ?follow=1; query: ?pod=&container=&tailLines=&previous=&follow=
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/eventsestate.readEvent[]; query: ?limit= (max 500)
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/replicasetsestate.read{replicaSets:[{name, createdAt, version, image?, current, backAt?, ran?}]}, a Deployment's kept ReplicaSets from orbit-api's cache, oldest first, under no feature switch: version is the one its pods run when their spans carry no service.version (the app's container's image tag, with the pod-template hash beside a repeated tag, else the hash), image that container's image when one is told apart, current the highest revision. When the current one is older than another, backAt is when the Deployment went back to it (the last span of a newer one that ran, else its Progressing condition) and each newer one says whether it ran. Any other kind answers an empty list
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/scaleworkloads.writeWriteResult; body {replicas, dryRun, resourceVersion?}
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/resourcesworkloads.writeWriteResult; body {container, requests:{cpu,memory}, limits:{cpu,memory}, dryRun, resourceVersion?}
GET /clusters/{id}/workloads/{ns}/Deployment/{name}/revisionsestate.read{revisions:[{revision, name, createdAt, images, changeCause, replicas, current}], rollout:{outcome, desired, updated, ready, available}}, newest first, read from the API server; outcome is progressing, completed or failed (ProgressDeadlineExceeded), as kubectl rollout status reads it
GET /clusters/{id}/workloads/{ns}/Deployment/{name}/releasesapm.read and estate.readThe release scorecard (apm.md → "Releases of a Deployment"): {services, logs, revisions:[{revision, name, createdAt, images, changeCause, current, rolledOutAt, reapplied, beforeMs, afterMs, services:[{service, before, after, newRoutes, goneRoutes, more4xx}], newErrors, restarts, verdict, worse}]}, newest first. before and after are {requests, errors, server, http4xx, p95Ms} over the beforeMs before rolledOutAt (the run of the revision it replaced) and the afterMs after it (its own run), 30 minutes each at most; http4xx is null where the engine was not counting 4xx at the window's start; verdict is worse (with worse naming errors, latency, 4xx, newErrors, restarts), ok, few, noEntry or none. newErrors is null when the role lacks logs.read, stored logs are off or the read failed. Gated by the apm switch, not rollback
POST /clusters/{id}/workloads/{ns}/Deployment/{name}/rollbackworkloads.writeWriteResult; body {toRevision?, dryRun, resourceVersion?}; kubectl rollout undo: 0 or none is the previous revision. The apply is one JSON patch that first tests the dry run's resourceVersion, then replaces the pod template. A paused Deployment, the current revision, a template already equal and orbit-api's own namespace are refused. The apply needs X-Orbit-Confirmed set to the Deployment's name as the operator typed it, or it is 400 confirmation_required. The answer adds changes, one entry per changed field ({container, field, from, to}, or {container, field: "env", added, removed, changed}): env by name only, a valueFrom by its source, never a value. An applied rollback is followed every 5 s for up to 15 minutes and audited as workload.rollback.result
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/restartworkloads.writeWriteResult; body {dryRun, resourceVersion?}; kubectl rollout restart on a Deployment, StatefulSet or DaemonSet: a strategic merge patch of the pod template's kubectl.kubernetes.io/restartedAt to now (RFC 3339, UTC) and nothing else, pinned to the resourceVersion, so the controller replaces the pods by its own update strategy. diff is restartedAt: <before> -> <after>. A CronJob, a paused Deployment and an OnDelete StatefulSet or DaemonSet are refused with 400 (its controller would roll nothing; kubectl stamps it anyway). The apply needs X-Orbit-Confirmed set to the workload's name as the operator typed it, or it is 400 confirmation_required. Audited as workload.restart
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/rolloutestate.read{outcome, desired, updated, ready, available} for a Deployment, StatefulSet or DaemonSet, read from the API server as kubectl rollout status reads it: what the Deck polls after a restart. failed is a Deployment's ProgressDeadlineExceeded, the other two only progress or complete
POST /clusters/{id}/workloads/{ns}/CronJob/{name}/suspendworkloads.writeWriteResult; body {suspend, dryRun, resourceVersion?}
POST /clusters/{id}/workloads/{ns}/CronJob/{name}/triggerworkloads.writeWriteResult with after.job, the Job copied from the CronJob's template; body {dryRun, resourceVersion?}
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/configconfig.readWorkloadConfig: each container's env and envFrom with where each value comes from, each reference's status, masked values, and which objects changed after the pods started; audited
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/config/revealconfig.read{name, value, source, object?, key?}; body {container, name}; one masked value, audited without it
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/manifestconfig.readThe controller as the API server holds it, as JSON, less managedFields and the last-applied copy, each value a credential would hold masked as a diff masks it ([redacted]); Cache-Control: no-store, audited as workload.manifest.view; the demo estate answers 400
GET /nocturne/sessionsnocturne.use{sessions: [{id, title, clusterId, turns, createdAt, updatedAt, expiresAt}]}, the caller's own, newest first; 403 for a demo account
GET /nocturne/sessions/{id}nocturne.use{id, title, clusterId, createdAt, updatedAt, expiresAt, turns}; 404 when unknown, expired or someone else's
PUT /nocturne/sessions/{id}nocturne.use{id, updatedAt, expiresAt}; body {title, clusterId, turns}, at most 80 turns and 256 KiB; kept ORBIT_CHAT_RETENTION after the last save, 30 per user
DELETE /nocturne/sessions/{id}nocturne.use204

The routes of Addendum v0.5 (identity, audit, dashboards, APM, alert acknowledgements) and Nocturne's read routes follow the entity shapes, each in its own section.

Node groups have no endpoint of their own: grouping is a view concern, done client-side over GET /clusters/{id}/nodes.

Entity shapes (documented-by-example; see the provenance note above)

Every timestamp on this API is epoch MILLISECONDS, because that is what Date, uPlot and Intl take in the browser. No RFC 3339 crosses this boundary except builtAt on /version and checkedAt on /nocturne/models. Ages are pre-formatted strings the way kubectl prints its AGE column (312d, 14h, 26m), not durations to parse.

Both backings (the deterministic demo estate and the live Kubernetes source) serve exactly these shapes, so the Deck cannot tell which one answered.

text
Cluster {
  id, name: string
  env: "production" | "staging"
  region, version, platformVersion: string   // "us-east-1", "1.31", "eks.8"
  status: "healthy" | "degraded" | "critical"
  nodes, pods, namespaces: number
  cpu: { used, capacity: number }            // vCPU
  memory: { used, capacity: number }         // GiB
  monthlyCost: number
  age: string
}

Node {
  name, cluster, nodeGroup, instanceType: string
  capacityType: "ON_DEMAND" | "SPOT"
  az, kubeletVersion, age: string
  pods, maxPods: number
  cpu: { used, capacity: number }            // vCPU
  memory: { used, capacity: number }         // GiB
  status: "Ready" | "NotReady" | "SchedulingDisabled"
}

Workload {
  id: string                                 // "<cluster>/<namespace>/<name>"
  cluster, namespace, name: string
  kind: "Deployment" | "StatefulSet" | "DaemonSet" | "CronJob"
  ready, desired: number
  image: string
  cpu: { used, request: number }             // millicores
  memory: { used, request: number }          // MiB
  restarts: number
  status: "running" | "progressing" | "degraded" | "failed"
  age: string
}

Event {
  id, cluster: string
  ts: number                                 // epoch ms
  type: "Normal" | "Warning"
  reason, message: string
  object: string                             // "pod/checkout-api-6f4b7c-2xk8p"
  count: number
}

Alert {
  id, cluster: string
  severity: "critical" | "warning" | "info"
  name, namespace, workload, summary: string
  since: number                              // epoch ms
  durationMin: number
  runbook: string
  state: "firing" | "pending"
  team: string                               // routing label; "" when derived
  ack: "open" | "acked" | "silenced"
  lastChange: number                         // epoch ms
  signal: "latency"|"cpu"|"memory"|"ingest"|"errors"|"cost"|"spot"
  args?: Record<string, string>               // the facts the summary was written from
  ackedBy?: string, ackedAt?: number          // set while acked or silenced
  silencedUntil?: number, ackNote?: string    // epoch ms; the note, up to 500 characters
}

FinOps {
  cluster: string
  monthly, forecast, deltaPct: number        // deltaPct is a ratio: 0.044 = +4.4%
  byNamespace, byNodeGroup: Array<{ key, label: string, monthly, deltaPct: number }>
  spot:  { coverage, target, savingsMonthly: number }   // coverage/target are ratios
  waste: { monthly, cpuIdle, memIdle: number, workloads: number }
  source: "demo" | "list-price" | "cost-explorer"
}

Recommendation {
  id, cluster, namespace, workload: string
  kind: "Deployment" | "StatefulSet" | "DaemonSet" | "CronJob" | "PersistentVolume"
  action: "rightsize" | "downscale" | "spot" | "hpa" | "storage"
  from, to: string       // millicores, MiB, GiB or a replica count, per `action`
  monthlySavings: number
  confidence: "high" | "medium" | "low"
}

Two notes that are easy to get wrong:

  • FinOps.source says where the money came from. "list-price" means an embedded us-east-1 on-demand price table times 730 hours, not a bill; see architecture.md → "What live mode reads, and what it derives". Anything presenting these numbers should say which it is.
  • Recommendation.kind and .action carry two values the demo estate never emits: "PersistentVolume" / "storage", for an orphan volume the live source found. They are the correct values for a real finding, which a Deployment value would misreport. A client that switches exhaustively on either union needs both added.

Alert.team is empty on every alert the live source derives: those rules come from cluster state, not from a PrometheusRule with routing labels on it, and inventing an owner pages the wrong people.

The workloadRef the Deck puts in a URL is "<namespace>~<name>". It is built client-side from the two fields above; no endpoint returns it.

QueryResult, the shape every chart on the site consumes

This one is spelled out in CONTRACT.md directly: "uPlot/chart friendly."

text
QueryResult {
  series: Array<{ key: string, label: string, points: Array<[number, number]> }>
  unit: "ms" | "rps" | "pct" | "usd" | "bytes" | "count" | "ratio"
}

Each point is [epoch-ms, value]: milliseconds, where a Prometheus API returns seconds; orbit-api converts. GET /query_range is bounded (see Limits below), so a caller cannot request a window/step combination that would return an unbounded number of points.

GET /query_range parameters

ParamRequiredAccepted formatDefault
clusteryesA cluster id from GET /clusters, ≤128 chars. An unknown one is 404.none
expryesA MetricKey (below) or raw PromQL. ≤2000 runes.none
fromnoRFC 3339 (2026-03-14T08:26:53Z) or Unix seconds (1300000000; a fractional value is truncated).to minus 1 hour
tonoSame two formats as from.now, truncated to the second
stepnoA Go duration (30s, 5m, 1h) or bare seconds (300). Rounded to the second.60s

from must be strictly before to. The window, the step and the resulting point count are all bounded; see Limits.

expr: the twelve panel keys, and ad-hoc PromQL

The Deck's built-in panels send one of twelve fixed MetricKeys (request_rate_by_cluster, error_rate_by_cluster, cost_daily, latency_percentiles, request_rate_by_service, error_budget_burn, ingest_rate, active_series, disk_per_block, cpu_saturation, query_latency, spot_coverage). Both backings answer all twelve with the same unit, so a panel's axis does not depend on which one replied. Live, the four request keys (request_rate_by_cluster, error_rate_by_cluster, latency_percentiles, request_rate_by_service) read the entry spans' span metrics where no app exports http_*, and error_budget_burn draws one line per service SLO, none without one (apm.md).

Anything else is treated as raw PromQL for the ad-hoc query panel:

  • Live source with ORBIT_STACK_URL set: the expression goes to the engine verbatim. unit is "bytes" when the expression names a *_bytes metric and "count" otherwise: the engine returns a number and orbit-api does not claim to know what it means. Each returned series is keyed by Prometheus's own rendering of its label set: node_memory_MemFree_bytes{instance="n1"}, or the metric name alone when that is the only label.
  • The demo estate with ORBIT_STACK_URL set: the expression runs on the real engine as well. The twelve keys keep the estate's own numbers; anything else is PromQL, which is what every dashboard panel sends.
  • No ORBIT_STACK_URL, live or demo: 400 invalid_request, saying ad-hoc PromQL needs the live source (ORBIT_DEMO_DATA=false) and ORBIT_STACK_URL (the message predates the demo case above; the engine is what it needs). There is no engine to evaluate it, and orbit-api refuses rather than draw a generated line that looks like an answer.
  • An expression the engine rejects (errorType bad_data or execution) is 400 invalid_request carrying the engine's own message. An engine that timed out or is not there (timeout, canceled, unavailable, or any other failure) is 502 upstream_error. The split keeps a bad query, which is the caller's fault, apart from an outage, which is not.

A MetricKey the estate has no data for returns an empty series array with the correct unit, never a fabricated line.

The workload detail surface (CONTRACT.md Addendum v0.4)

Four routes under one workload. {kind} is Deployment, StatefulSet, DaemonSet or CronJob; {ns} and {name} are the workload's own.

Logs. ?tailLines= defaults to 200 and is capped at 5000; one non-following response carries at most 2 MiB. ?previous=1 reads the container that exited, which is the one an operator opens this screen for. Without ?follow=1 the body is plain text. With it, the body is the SSE vocabulary this contract already has: event: token with {"text": "<one line>"}, event: done last with finishReason (stop, shutdown when a rollout drained the pod, error). There is no fifth frame type.

The pod and container are validated against the workload's own pods: pods/log is namespace scoped, and a query parameter must not become a way to read a neighbour's container. Every response says what it read and what else there is, so no separate inventory endpoint exists:

text
X-Orbit-Pod: checkout-api-6f4b7c-aaaaa
X-Orbit-Container: app
X-Orbit-Pods: checkout-api-6f4b7c-aaaaa=app|sidecar,checkout-api-6f4b7c-bbbbb=app|sidecar

Events are the workload's, not the namespace's: orbit-api matches the controller, the ReplicaSets or Jobs under it, and its pods, because Kubernetes files one story against all three: the scale against the Deployment, the pod creation against the ReplicaSet, and the image pull, the probe failure and the OOMKill against the pod. Matching on name alone would drag in every Service and ConfigMap that shares the workload's name.

Writes are off unless an operator turned them on. With ORBIT_WRITE_ENABLED unset or false, scale and resources answer 403 writes_disabled, and the chart renders no write ClusterRole either. The privilege and the switch are separate, and a write needs both. The role grants patch, and only patch, on apps/{deployments,statefulsets,daemonsets} and on deployments/scale and statefulsets/scale.

The operator gate, on web and not on orbit-api. The proxy attaches ORBIT_AUTH_TOKEN to everything it forwards, so from orbit-api's side every caller through the front door is authenticated. That is correct for reads and was a hole for writes: a bare curl at the ingress carried no credential of its own and still scaled a Deployment. A mutating method on .../scale or .../resources is now forwarded only when both hold:

  1. X-Orbit-Operator-Token equals ORBIT_DECK_WRITE_TOKEN on the web server (constant-time compare). The token is spent on that hop and is never forwarded to orbit-api.
  2. The request proves it is same-origin: Sec-Fetch-Site: same-origin or none, or an Origin whose host matches. Neither header present means it is not a browser, and the token alone decides.

Otherwise 401 unauthorized (missing, wrong, or cross-site) or 403 writes_disabled when no token is configured. In every case web answers without contacting orbit-api, so a refused write is not an oracle for which workloads exist. Reads are never gated; other mutating routes (contact, the assistant stream) keep working but are refused cross-site.

The Deck asks for the token once an hour and sends it once, to POST /api/operator on web, which checks it and answers with an HttpOnly, SameSite=Strict cookie holding an expiry and an HMAC keyed by the token, never the token itself. Browser storage and URLs never hold it. web accepts that cookie on a same-origin write only; a 401 asks for the token again.

Every write is a dry run the caller confirms. Post with "dryRun": true: orbit-api patches with DryRun: All, so the API server, with its webhooks, its defaulting and its LimitRanges, decides what would happen, and the answer carries the diff plus the object's resourceVersion. Post the same body with "dryRun": false and that resourceVersion to apply it. An apply with no resourceVersion is 400; an apply whose object has moved is 409 conflict, which retrying the same body does not fix, because the diff the caller approved no longer describes the cluster.

text
WriteResult {
  kind, namespace, name: string
  container?: string
  before, after: Record<string, string>   // "replicas", "requests.cpu", "limits.memory"
  diff: string[]                          // ["replicas: 1 -> 3"], sorted, unchanged fields omitted
  resourceVersion: string
  dryRun, applied: boolean
}

An empty quantity in resources leaves that field as it is: clearing a limit and not touching it are different operations. replicas is 0..1000. A DaemonSet has no scale subresource (it runs one pod per matching node), so a scale on one is 400 rather than a control the cluster would ignore.

Every attempt, refusals included, is one structured log line with principal, console, client_ip and managed_by, one increment of orbit_workload_writes_total{verb,kind,outcome,principal} with outcome in applied, dry_run, refused, failed, and one audit event, workload.scale or workload.resources (Addendum v0.5). principal is the signed-in user, whose username is already bounded to [a-z0-9._-] and 32 characters, so a header cannot mint unbounded time series. console is X-Orbit-Principal, the label web sets from ORBIT_DECK_OPERATOR; orbit-api believes that header only on a request authenticated with its own shared bearer, which only web holds.

On the demo estate events is a fixed, plausible list; logs is 400 invalid_request naming ORBIT_DEMO_DATA=false; both writes are 403 writes_disabled. No container sits behind a table in a process, so orbit-api refuses rather than generate a log line that looks like an answer.

Identity (CONTRACT.md Addendum v0.5)

Sign-in, sessions, users and roles. Bodies are one JSON object of at most 16 KiB, and an unknown field is 400. The whole public list is GET /healthz, GET /readyz, GET /auth/state, POST /auth/login, POST /auth/setup and POST /contact; every other route needs a session. identity.md explains each rule; this is the reference.

RoutePermissionBody and answer
GET /auth/statepublic{setupRequired, demo, demoUsers?: [{username, role}]}
POST /auth/loginpublic{username, password} → {token, expiresAt, user, role: {id, name}, permissions, session: {id, expiresAt}}. 401 wrong credentials, 403 forbidden disabled account, 429 + Retry-After while a wait runs. Through web, its own route sets the cookie and strips token.
POST /auth/setuppublic{setupCode, username, name, password} → 201 {user}, only while no user exists; 401 wrong code, 409 users exist
POST /auth/logoutsession204; the session is revoked. Through web, the cookie is cleared whatever orbit-api answered.
GET /auth/mesession{user, role: {id, name}, permissions, session: {id, expiresAt}}
POST /auth/passwordsession{current, next} → 204; a wrong current is 400; every other session of the user ends
GET /users, POST /usersusers.manage{users: [user]}; {username, name, email, role, password} → 201 {user}, 409 for a taken username
PATCH /users/{id}, DELETE /users/{id}users.manageAny of name, email, role, disabled, password → {user}; DELETE → 204
POST /users/{id}/revoke-sessionsusers.manage{revoked}, the number of sessions ended
GET /roles, POST /rolesusers.manage{roles: [role], permissions: [the closed set]}; {name, description, permissions} → 201 {role}
PATCH /roles/{id}, DELETE /roles/{id}users.manageAny of name, description, permissions → {role}; DELETE → 204
text
user { id, username, name, email, role, disabled,
       createdAt, updatedAt, lastLoginAt /* 0 = never */, lastLoginIp, activeSessions }
role { id, name, description, builtin, permissions[], users /* how many hold it */ }

Refusals that protect the install: a built-in role cannot change (400); a role in use cannot be deleted (409); nobody changes their own role, disables or deletes themselves (400); no change may leave zero enabled users holding users.manage (409). Every change is an audit event.

The audit trail

GET /audit (audit.read) takes from, to (epoch ms, both inclusive, default the last 24 h), actor, action, outcome, q, limit (1 to 1000, default 100) and cursor, and answers newest first:

text
{ events: [{ id, ts, actor: {id, username, role} | null, action,
             target: {type, id, name}, outcome: "success" | "denied" | "failure",
             ip, userAgent, requestId, details }],
  nextCursor,                                    // "" on the last page
  total, facets: { action, actor, outcome },     // [{value, count}], whole window
  interval, histogram: [{ t, n, denied, failure }] }

format=csv streams every match of the same filters instead, at most 100,000 rows. The search language of q, the event list and the retention are in audit.md.

Dashboards and the engine's metadata

RoutePermissionBody and answer
GET /dashboards?q&tagdashboards.read{dashboards: [{uid, title, description, tags, provisioned, createdBy, updatedAt, updatedBy, panels}]}, panels a count; q matches title, description and tags, tag one tag exactly
GET /dashboards/{uid}dashboards.read{dashboard, meta: {version, provisioned, canEdit, canWrite, createdAt, createdBy, updatedAt, updatedBy}}
POST /dashboardsdashboards.write{dashboard} → 201, same shape; no uid mints one, a taken or provisioned uid is 409
PUT /dashboards/{uid}dashboards.write{dashboard, version} → the same shape at the next version; 409 with version, updatedBy, updatedAt beside error when the stored version moved; 403 on a provisioned dashboard
DELETE /dashboards/{uid}dashboards.write204; 403 on a provisioned dashboard
GET /labels, GET /label/{name}/values, GET /series, GET /query, GET /status/tsdbtelemetry.queryThe engine's own Prometheus body

Dashboard bodies may reach 1 MiB. The model, its closed sets and its bounds are in dashboards.md. The four metadata routes carry only match[] (at most 20), start, end, limit (default 5000 on the label and series routes), query and time to the engine; a failure is the contract envelope with the engine's message (bad_data or execution is 400 invalid_request, anything else 502 upstream_error), an answer over 16 MiB is 502, and no ORBIT_STACK_URL is 503 not_ready.

APM

Seven reads, apm.read, forwarded to the engine at ORBIT_STACK_URL with its bearer; the status and body are the engine's. Span times are epoch microseconds (startUs, durationUs), every other time epoch milliseconds. start and end default to the last hour and span at most 31 days.

RouteAnswer
GET /traces/{traceId}?start&end{traceId, startUs, durationUs, services[], spans: [{spanId, parentSpanId, name, service, kind, startUs, durationUs, status: {code, message}, attributes, resource, events: [{name, timeUs, attributes}]}]}; 404 outside the retention. start and end are optional, where the caller saw the trace (one stands for both): the engine reads only the segments within an hour of them, and every segment when those hold none of the trace
GET /traces?service&operation&status&minDurationMs&maxDurationMs&attr=k=v&start&end&limit&root&rootKind{traces: [{traceId, rootService, rootName, startMs, durationMs, spanCount, errorCount, services: [{name, spans, errors}], rootKind}], truncated}; rootKind only with root or rootKind
GET /spans?service&name&kind&status&minDurationMs&traceId&attr=k=v&start&end&limit{spans: [{traceId, spanId, parentSpanId, service, name, kind, status, startNs, endNs, durationMs, attrs, resource}], truncated}, newest first
GET /apm/services?start&end{services: [{name, rate, errorRate, p50Ms, p95Ms, p99Ms, requests, errors, operations, resources: {namespace, deployment, pods[]}}]}
GET /apm/services/{service}/operations?start&end{operations: [{name, kind, rate, errorRate, p50Ms, p95Ms, p99Ms, requests, errors}]}
GET /apm/servicemap?start&end{nodes: [{id, type, rate, errorRate, p95Ms}], edges: [{source, target, rate, errorRate, p95Ms, requests, backgroundRate?}], partial, unpairedSpans}; partial is true when spans went unpaired in the window (unpairedSpans of them), so the edges undercount; backgroundRate, of rate, is a service's calls with no request around them, absent on an edge no client span made and where the window holds no count of them
GET /apm/heatmap?start&end&step&service&operation&status&kind&attr=k=v&notAttr=k=v&source&timeout{source, start, end, from, step, columns, bounds, cells: [{t, durationBucket, count}], total, partial, ingest: {window, spansSeen, spansKept}}: span durations over the window, the latency heatmap (apm.md)

traceId is 1 to 32 hex digits, left-padded. kind is server, client, producer, consumer, internal or unspecified; a status code is ok, error or unset; a map node's type is service, database, external or queue. In a search, status is error (a span failed) or ok (none did), the durations bound the whole trace, attr repeats up to 8 times and every one must hold on a span, an event or the resource, service and operation are at most 512 bytes, and limit is 20 by default and at most 1000, newest first, with truncated when there were more. root=true keeps root traces and rootKind (a comma list of kinds) those whose root span has one of them (apm.md). A trace read returns the hop parts its spans name in orbit.hop.trace_id under its own id. On /spans, start and end take fractions of a millisecond, limit is 100 by default and at most 10000, and attr matches the span, an event or the resource. rate is requests per second over the window and errorRate a ratio from 0 to 1.

In a heatmap, bounds are the rows' upper bounds in ms, ascending: row b holds durations in (bounds[b-1], bounds[b]] and row bounds.length the ones past the last. Column i starts at from + i * step; the first and last columns hold only what falls inside [start, end]. cells lists the non-empty ones. source is metrics (every span, from the span metrics: a service's spans of kind entry, server and consumer, the default, or outgoing, client and producer; with no service, the service graph's calls from user) or traces (the stored traces the search would match, each once by its start and its duration as the search judges it, in one pass that answers partial when timeout cuts it). attr and notAttr, or operation or status with no service, read traces; source forces one, and metrics with a filter it cannot hold is 400. step (ms) defaults to about 120 columns and is never finer than 15 s or than 360 columns. ingest is what the ingestion rules kept in the engine's last 5m, 1h or 24h, for a window that ends within 5 minutes of now. Without ORBIT_STACK_URL every APM route answers 503 not_ready, demo data or not, and an engine that does not answer is 502 upstream_error. apm.md covers what the engine derives these from.

Alert acknowledgements and silences

RoutePermissionBodyEffect
POST /clusters/{id}/alerts/{alertId}/ackworkloads.write{note?}ack: "acked"
DELETE /clusters/{id}/alerts/{alertId}/ackworkloads.writenoneback to open when it is acked
POST /clusters/{id}/alerts/{alertId}/silenceworkloads.write{minutes, note?}ack: "silenced" until then; minutes is 15, 60, 240 or 1440
DELETE /clusters/{id}/alerts/{alertId}/silenceworkloads.writenoneback to open when it is silenced

Each answers the alert as GET /clusters/{id}/alerts now shows it. A DELETE on an alert not in that state is a 200 that changes and records nothing. An unknown alert is 404, a duration off the list or a note over 500 characters 400. The rules behind each derived alert: alerts.md.

Nocturne's read routes

Nocturne's cluster tools read these routes beyond the ones above. nocturne calls them with the asking user's session, so a tool reads what that user may read. All GET; the demo estate answers pods, nodes and events from its own tables and refuses the others by name.

RoutePermissionQuery
/clusters/{id}/nocturne/podsestate.read?namespace=&kind=&workload=&node=&unhealthy=; without config.read every env value reads [redacted]
/clusters/{id}/nocturne/nodesestate.readnone
/clusters/{id}/nocturne/eventsestate.read?namespace=&kind=&name=&type=&limit=
/clusters/{id}/nocturne/promqltelemetry.query?query=&time=, or ?query=&start=&end=&step=
/clusters/{id}/nocturne/rightsizingestate.read?namespace=&kind=&name=&window=
/clusters/{id}/nocturne/servicesestate.read?namespace=&name=
/clusters/{id}/nocturne/configmapsconfig.read?namespace=&name=; each read writes configmap.view to the audit trail
/clusters/{id}/nocturne/checkestate.read?namespace=&kind=&name=&type=&patch=: applies a proposed patch to a copy of the live object in memory and answers whether the API server would take it. A patch that widens the pod (privileged, host namespaces, a hostPath volume, added capabilities, root, another service account, a new container, other command or args, an image from another repository) or a Service's reach (NodePort, LoadBalancer, external IPs) is refused, so Nocturne never prints its command

nocturne

Base path /api/v1/nocturne. Reached by the browser only through orbit-api's reverse proxy (POST /chat, POST /analyze and GET /models on orbit-api, same paths, streamed unbuffered, the service token swapped in on the hop); see architecture.md. From the browser that is web's own origin, like every other route. Every route requires auth and is subject to the chat/analyze limits below; the per-IP rate limiter applies here on every route, not only contact. On orbit-api's side of the hop, chat and analyze need the nocturne.use permission and models any signed-in user, and the proxy passes the user's X-Orbit-Session through to nocturne, whose tools call orbit-api back with it.

RouteReturns
POST /chattext/event-stream; see SSE frames below
POST /analyzeJSON, one-shot cluster analysis
GET /modelsConfigured tiers and whether each is reachable

Model routing: tier is not a request field

Two tiers sit behind one interface: reasoning (analysis, root cause, FinOps plans) and fast (product help, formatting, short answers). tier is not part of the chat or analyze request body. Addendum v0.2 removed it deliberately: a client choosing its own tier, unauthenticated or careless, is the "choose which model tier to bill" problem the addendum exists to close. tier.Select classifies the request server-side and only that classification can reach the reasoning tier. nocturne still reports the chosen tier to the caller, in the done SSE frame and in a response header: you can always see what ran and never pick it.

GET /models responds with the provider, the two limits, and one entry per tier with a cached reachability probe (never per request: a polled /models must not become a bill). The provider credential is never included, and every upstream error string is redacted before it leaves the service:

text
{
  "provider": "mock" | "openai" | "anthropic",
  "maxTokens": 2048,
  "timeout": "2m0s",
  "tiers": [
    { "tier": "reasoning", "purpose": "analysis, root cause and FinOps plans",
      "model": "<NOCTURNE_REASONING_MODEL>", "configured": true, "reachable": true,
      "checkedAt": "<RFC 3339>", "error": "<redacted, only when unreachable>" },
    { "tier": "fast", "purpose": "product help, formatting and short answers",
      "model": "<NOCTURNE_FAST_MODEL>", "configured": true, "reachable": true,
      "checkedAt": "<RFC 3339>" }
  ]
}

SSE frame types (POST /chat)

Four event types, data: is always JSON:

event:data: payloadMeaning
token{"text": "..."}One incremental chunk of the assistant's reply.
tool{"name", "status", "detail"}The model invoked a tool/function.
done{"tier": "reasoning" | "fast", "model", "class", "routing", "provider", "finishReason", "usage": {"inputTokens","outputTokens"}, "durationMs"}Stream complete, always the last frame. Carries the tier that ran; see above. finishReason is stop, shutdown (a rollout drained the pod mid-answer), timeout or error.
error{"code","message"}code is from the same closed set as every other route. An event: error inside a 200 response counts as a failure for metrics purposes, not a success; see operations.md.

orbit-stack

The telemetry engine speaks Prometheus's API on port 8082: POST /api/v1/write (remote-write 1.0), GET|POST /api/v1/query_range, GET|POST /api/v1/query, GET|POST /api/v1/series, GET|POST /api/v1/labels, GET /api/v1/label/{name}/values, GET /api/v1/metadata, GET /api/v1/rules, GET|POST /api/v1/query_exemplars, GET|POST /api/v1/format_query, GET /api/v1/status/buildinfo, GET /api/v1/status/tsdb, POST /-/flush, plus the contract probes and /api/v1/version. Responses on the telemetry routes are in Prometheus's shapes, not the contract's, warnings included, so agents and dashboards need no adapter; its read routes are metered per client IP by ORBIT_STACK_QUERY_RPM and ORBIT_STACK_QUERY_BURST. The Deck never calls it directly: orbit-api translates the Deck's metric keys and passes ad-hoc PromQL through on GET /api/v1/query_range. Every route, parameter and the PromQL it answers are in orbit-stack.md.

Traces (Addendum v0.5) arrive on POST /v1/traces, OTLP/HTTP with protobuf or JSON bodies, gzip, zstd or neither, the same bearer as remote-write, answered in OTLP's own shapes (partial success, google.rpc.Status). The engine also serves the seven APM reads above at the same paths, in the contract's shapes and error envelope; orbit-api forwards them unchanged. apm.md has the receiver's answers and what to send.

Error codes, a closed set

CONTRACT.md fixes nine codes, Addendum v0.4 added writes_disabled and conflict, and Addendum v0.5 added forbidden. A service does not invent another:

CodeConventional HTTP statusMeaning
invalid_request400Malformed or semantically invalid request body/params.
unauthorized401 (fixed by contract)Missing, malformed, or invalid credential. Never says which.
not_found404No such resource (e.g. an unknown cluster id).
payload_too_large413Body exceeds the limit for that route; see Limits.
rate_limited429Per-IP limiter tripped; see Limits.
unsupported_media_type415Request body wasn't JSON.
not_ready503 (fixed by contract, matching /readyz's own semantics)A dependency isn't answering.
upstream_error502A downstream call (e.g. orbit-api → nocturne) failed.
internal_error500Unhandled server-side failure.
writes_disabled403This build never opted into writes (Addendum v0.4).
conflict409The object moved between the dry run and the confirmation (Addendum v0.4); since Addendum v0.5 also a taken username or dashboard uid, a dashboard saved by someone else since you read it, a role still in use, or a change that would leave no enabled user holding users.manage.
forbidden403The session is valid and its role lacks the route's permission; the message names it (Addendum v0.5). Also a disabled account at sign-in, and a write to a built-in dashboard.

The status-code column beyond the two CONTRACT.md fixes explicitly (unauthorized → 401, not_ready → 503) reflects ordinary REST convention for each code's meaning; CONTRACT.md's own guarantee is narrower and stronger than any specific number: "the matching HTTP status" always agrees with the code, on every route.

Limits, the complete list

The first block is CONTRACT.md's "Limits are part of the contract" section, verbatim; the rows after analyze come from the addenda that added their routes:

LimitValue
Request body, general1 MiB
Request body, POST /contact64 KiB
contact rate limit5 requests/minute, burst 3
Request timeout (all routes)20s
query_range: max points per response3000
query_range: max window90 days
query_range: max expr2000 runes
query_range: min step15s
query_range: max step24h
events: max returned500
logs: default / max tailLines200 / 5000
logs: max bytes, one non-following response2 MiB
scale / resources: request body16 KiB
scale: replicas0..1000
chat: max messages40
chat: max runes per message8000
chat: max total runes32000
chat: max system-prompt runes4000
analyze: max input runes24000
analyze: max output runes2000
Identity bodies (auth, users, roles, alert marks)16 KiB
Dashboard body1 MiB
Sign-in waits, per username5 failures free, then 1 s doubling to 1 min
Sign-in waits, per client address20 failures free, then doubling to 15 min
Sign-in routes, requests per minute30 per client address, 300 shared when the address is web's
Sessions per user100, the oldest ended first
Session lifetime12 h, absolute
audit: limit1..1000, default 100
audit: CSV rows100,000
Alert note500 characters
OTLP request body, once gzip or zstd is undone16 MiB, or ORBIT_STACK_MAX_BODY_BYTES if smaller
One trace in the engineORBIT_STACK_TRACE_MAX_BYTES, default 5 MiB
Trace search: limit1..1000, default 20
Trace search: attr filters8
Trace and APM window31 days
Heatmap columns360, about 120 by default
Heatmap step15 s at least

A request that exceeds any of these gets the matching closed error code (payload_too_large, invalid_request, or rate_limited) rather than a silent truncation. If you integrate against this API, check every limit above client-side before you send the request; the server-side check is a backstop.

Where to go next

  • What emits which metric, and what a saturated system looks like on this API: operations.md.
  • The auth failures above, explained from the threat-model side: security.md.
  • A 429 or a stuck SSE stream in practice: troubleshooting.md.