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 exceptGET /healthzandGET /readyz. Onorbit-api, a signed-in user rides on top of it asX-Orbit-Session, which every route needs except the short public list in "Identity" below: no or bad session is401 unauthorized, a role without the route's permission403 forbidden. Seesecurity.mdandidentity.md. - From the browser, every path below is called against
web's own origin (e.g.https://your-host/api/v1/clusters), andweb's server forwards it toorbit-apiunchanged, attaching the bearer and copying theorbit_sessioncookie intoX-Orbit-Session. There is no separate public hostname fororbit-api. If you're calling a service directly for debugging (for example the debug portsdocker-compose.ymlpublishes), attach the bearer yourself; seeinstall/docker-compose.md. - Compression: through
web, a JSON answer of 1 KiB or more crosses withContent-Encoding: gzipwhen the request accepts it. An SSE stream never does, andcurlwithout--compressedgets the same JSON plain.orbit-apiitself answers plain. - Logs, not responses: every request gets one
slogJSON line on stdout (method, path, status, duration), regardless of outcome. Seeoperations.md.
Routes every backend service exposes
| Route | Returns | Auth? | Notes |
|---|---|---|---|
GET /healthz | 200 {"status":"ok"} | No (always exempt) | Liveness. Never touches a dependency, so a slow nocturne cannot fail orbit-api's liveness check. |
GET /readyz | 200 when dependencies answer, 503 otherwise | No (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 /metrics | Prometheus exposition | N/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"} | Yes | Requires 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.
| Route | Permission | Returns |
|---|---|---|
GET /clusters | estate.read | Cluster[] |
GET /clusters/{id} | estate.read | Cluster |
GET /clusters/{id}/nodes | estate.read | Node[] |
GET /clusters/{id}/workloads | estate.read | Workload[]; query: ?namespace=&kind=&q= |
GET /clusters/{id}/events | estate.read | Event[]; query: ?limit= (max 500, see Limits) |
GET /clusters/{id}/components | telemetry.query and estate.read | Component[]: 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}/alerts | estate.read | Alert[], with the acknowledgement fields below |
GET /clusters/{id}/changes | estate.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}/finops | estate.read | FinOps |
GET /clusters/{id}/recommendations | estate.read | Recommendation[] |
GET /query_range | telemetry.query | QueryResult; query: ?cluster=&expr=&from=&to=&step= |
POST /contact | public | 202 {"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 /leads | users.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}/logs | logs.read | text/plain, or text/event-stream with ?follow=1; query: ?pod=&container=&tailLines=&previous=&follow= |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/events | estate.read | Event[]; query: ?limit= (max 500) |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/replicasets | estate.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}/scale | workloads.write | WriteResult; body {replicas, dryRun, resourceVersion?} |
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/resources | workloads.write | WriteResult; body {container, requests:{cpu,memory}, limits:{cpu,memory}, dryRun, resourceVersion?} |
GET /clusters/{id}/workloads/{ns}/Deployment/{name}/revisions | estate.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}/releases | apm.read and estate.read | The 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}/rollback | workloads.write | WriteResult; 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}/restart | workloads.write | WriteResult; 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}/rollout | estate.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}/suspend | workloads.write | WriteResult; body {suspend, dryRun, resourceVersion?} |
POST /clusters/{id}/workloads/{ns}/CronJob/{name}/trigger | workloads.write | WriteResult with after.job, the Job copied from the CronJob's template; body {dryRun, resourceVersion?} |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/config | config.read | WorkloadConfig: 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/reveal | config.read | {name, value, source, object?, key?}; body {container, name}; one masked value, audited without it |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/manifest | config.read | The 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/sessions | nocturne.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.use | 204 |
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.
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.sourcesays where the money came from."list-price"means an embedded us-east-1 on-demand price table times 730 hours, not a bill; seearchitecture.md→ "What live mode reads, and what it derives". Anything presenting these numbers should say which it is.Recommendation.kindand.actioncarry 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 aDeploymentvalue 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."
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
| Param | Required | Accepted format | Default |
|---|---|---|---|
cluster | yes | A cluster id from GET /clusters, ≤128 chars. An unknown one is 404. | none |
expr | yes | A MetricKey (below) or raw PromQL. ≤2000 runes. | none |
from | no | RFC 3339 (2026-03-14T08:26:53Z) or Unix seconds (1300000000; a fractional value is truncated). | to minus 1 hour |
to | no | Same two formats as from. | now, truncated to the second |
step | no | A 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_URLset: the expression goes to the engine verbatim.unitis"bytes"when the expression names a*_bytesmetric and"count"otherwise: the engine returns a number andorbit-apidoes 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_URLset: 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:400invalid_request, sayingad-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, andorbit-apirefuses rather than draw a generated line that looks like an answer. - An expression the engine rejects (
errorTypebad_dataorexecution) is400invalid_requestcarrying the engine's own message. An engine that timed out or is not there (timeout,canceled,unavailable, or any other failure) is502upstream_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:
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|sidecarEvents 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:
X-Orbit-Operator-TokenequalsORBIT_DECK_WRITE_TOKENon the web server (constant-time compare). The token is spent on that hop and is never forwarded toorbit-api.- The request proves it is same-origin:
Sec-Fetch-Site: same-originornone, or anOriginwhose 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.
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.
| Route | Permission | Body and answer |
|---|---|---|
GET /auth/state | public | {setupRequired, demo, demoUsers?: [{username, role}]} |
POST /auth/login | public | {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/setup | public | {setupCode, username, name, password} → 201 {user}, only while no user exists; 401 wrong code, 409 users exist |
POST /auth/logout | session | 204; the session is revoked. Through web, the cookie is cleared whatever orbit-api answered. |
GET /auth/me | session | {user, role: {id, name}, permissions, session: {id, expiresAt}} |
POST /auth/password | session | {current, next} → 204; a wrong current is 400; every other session of the user ends |
GET /users, POST /users | users.manage | {users: [user]}; {username, name, email, role, password} → 201 {user}, 409 for a taken username |
PATCH /users/{id}, DELETE /users/{id} | users.manage | Any of name, email, role, disabled, password → {user}; DELETE → 204 |
POST /users/{id}/revoke-sessions | users.manage | {revoked}, the number of sessions ended |
GET /roles, POST /roles | users.manage | {roles: [role], permissions: [the closed set]}; {name, description, permissions} → 201 {role} |
PATCH /roles/{id}, DELETE /roles/{id} | users.manage | Any of name, description, permissions → {role}; DELETE → 204 |
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:
{ 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
| Route | Permission | Body and answer |
|---|---|---|
GET /dashboards?q&tag | dashboards.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 /dashboards | dashboards.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.write | 204; 403 on a provisioned dashboard |
GET /labels, GET /label/{name}/values, GET /series, GET /query, GET /status/tsdb | telemetry.query | The 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.
| Route | Answer |
|---|---|
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¬Attr=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
| Route | Permission | Body | Effect |
|---|---|---|---|
POST /clusters/{id}/alerts/{alertId}/ack | workloads.write | {note?} | ack: "acked" |
DELETE /clusters/{id}/alerts/{alertId}/ack | workloads.write | none | back to open when it is acked |
POST /clusters/{id}/alerts/{alertId}/silence | workloads.write | {minutes, note?} | ack: "silenced" until then; minutes is 15, 60, 240 or 1440 |
DELETE /clusters/{id}/alerts/{alertId}/silence | workloads.write | none | back 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.
| Route | Permission | Query |
|---|---|---|
/clusters/{id}/nocturne/pods | estate.read | ?namespace=&kind=&workload=&node=&unhealthy=; without config.read every env value reads [redacted] |
/clusters/{id}/nocturne/nodes | estate.read | none |
/clusters/{id}/nocturne/events | estate.read | ?namespace=&kind=&name=&type=&limit= |
/clusters/{id}/nocturne/promql | telemetry.query | ?query=&time=, or ?query=&start=&end=&step= |
/clusters/{id}/nocturne/rightsizing | estate.read | ?namespace=&kind=&name=&window= |
/clusters/{id}/nocturne/services | estate.read | ?namespace=&name= |
/clusters/{id}/nocturne/configmaps | config.read | ?namespace=&name=; each read writes configmap.view to the audit trail |
/clusters/{id}/nocturne/check | estate.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.
| Route | Returns |
|---|---|
POST /chat | text/event-stream; see SSE frames below |
POST /analyze | JSON, one-shot cluster analysis |
GET /models | Configured 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:
{
"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: payload | Meaning |
|---|---|---|
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:
| Code | Conventional HTTP status | Meaning |
|---|---|---|
invalid_request | 400 | Malformed or semantically invalid request body/params. |
unauthorized | 401 (fixed by contract) | Missing, malformed, or invalid credential. Never says which. |
not_found | 404 | No such resource (e.g. an unknown cluster id). |
payload_too_large | 413 | Body exceeds the limit for that route; see Limits. |
rate_limited | 429 | Per-IP limiter tripped; see Limits. |
unsupported_media_type | 415 | Request body wasn't JSON. |
not_ready | 503 (fixed by contract, matching /readyz's own semantics) | A dependency isn't answering. |
upstream_error | 502 | A downstream call (e.g. orbit-api → nocturne) failed. |
internal_error | 500 | Unhandled server-side failure. |
writes_disabled | 403 | This build never opted into writes (Addendum v0.4). |
conflict | 409 | The 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. |
forbidden | 403 | The 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:
| Limit | Value |
|---|---|
| Request body, general | 1 MiB |
Request body, POST /contact | 64 KiB |
contact rate limit | 5 requests/minute, burst 3 |
| Request timeout (all routes) | 20s |
query_range: max points per response | 3000 |
query_range: max window | 90 days |
query_range: max expr | 2000 runes |
query_range: min step | 15s |
query_range: max step | 24h |
events: max returned | 500 |
logs: default / max tailLines | 200 / 5000 |
logs: max bytes, one non-following response | 2 MiB |
scale / resources: request body | 16 KiB |
scale: replicas | 0..1000 |
chat: max messages | 40 |
chat: max runes per message | 8000 |
chat: max total runes | 32000 |
chat: max system-prompt runes | 4000 |
analyze: max input runes | 24000 |
analyze: max output runes | 2000 |
Identity bodies (auth, users, roles, alert marks) | 16 KiB |
| Dashboard body | 1 MiB |
| Sign-in waits, per username | 5 failures free, then 1 s doubling to 1 min |
| Sign-in waits, per client address | 20 failures free, then doubling to 15 min |
| Sign-in routes, requests per minute | 30 per client address, 300 shared when the address is web's |
| Sessions per user | 100, the oldest ended first |
| Session lifetime | 12 h, absolute |
audit: limit | 1..1000, default 100 |
audit: CSV rows | 100,000 |
| Alert note | 500 characters |
| OTLP request body, once gzip or zstd is undone | 16 MiB, or ORBIT_STACK_MAX_BODY_BYTES if smaller |
| One trace in the engine | ORBIT_STACK_TRACE_MAX_BYTES, default 5 MiB |
Trace search: limit | 1..1000, default 20 |
Trace search: attr filters | 8 |
| Trace and APM window | 31 days |
| Heatmap columns | 360, about 120 by default |
| Heatmap step | 15 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
429or a stuck SSE stream in practice:troubleshooting.md.