REST API reference

Configure an org-scoped app

Saves (default), resets, or refreshes version discovery for one app's org-scoped configuration. Sensitive values are tokenized server-side. Requires the `ManageOrgApps` permission. `reset` returns 204.

Configure a project-scoped app

Saves (default), resets, or refreshes version discovery for one app's project-scoped configuration. Sensitive values are tokenized server-side. Requires the `ManageProjectApps` permission. `reset` returns 204.

Get the current user

Returns the user identified by the session cookie or bearer API key. Requires authentication.

Get an organization's billing account

Returns the org's billing account: plan, billing interval, cycle anchor, and next billing date. Requires the `read_billing` permission. Unknown orgs or orgs without an account are 404.

List an organization's invoices

Lists the org's invoices, newest first, with offset pagination. Requires the `read_billing` permission.

Get one invoice

Returns a single invoice for the org. Requires the `read_billing` permission. Malformed invoice IDs are 400; unknown or foreign invoices are 404.

Get an invoice's line items

Returns the per-pool line items and computed total for an invoice. Requires the `read_billing` permission.

Get the upcoming (draft) invoice

Returns the org's latest draft invoice with its line items. Requires the `read_billing` permission; 404 when no draft exists.

List downloads

Returns every published download repository with its version tags, newest release first and the floating `default` tag last, plus the title and description the publisher annotated the served artifact with when it carries them. Unauthenticated: downloads are public.

Get a download

Returns one download repository: the publisher's title and description when annotated, its version tags and, per tag, the files with size, platform, and sha256 digest. The digest is the file's own sha256 — download bytes are stored verbatim. Unauthenticated: downloads are public.

The on-prem plan catalog (public)

Public (no authentication): the machine-readable twin of the pricing page's On-prem pane, in the same display order. `price.amount` is in the minor unit of `price.currency` (49900 is $499.00) and `limits.active_nodes` is -1 for unlimited. Cacheable for five minutes; an empty catalog answers an empty list.

Read a node's retained top-process contributors

The bounded union of the largest CPU, resident-memory and disk-I/O consumers retained per scan window, newest window first. Absence from a window's list means the process was not retained, not that it did not run or used nothing; each window carries how many processes were scanned, offered and admitted so coverage is visible. Contributors have their own short retention, independent of the metric tiers.

List a node's metric devices

Every (family, device) pair the node has reported — block devices, interfaces and mount points — with the first and last time each was seen. Block devices are parents only: a disk's counters already include its partitions, so the two are never added together. Each row also names the application it belongs to — empty for the host's own series — so one call tells a caller both which devices and which applications this node has metrics for.

Read one node's host metrics

Returns one catalog family's series for a node over a time range. The store picks the tier that fits the point budget and says which one it used, how far it is finalized, how fresh the last sample is, and where the gaps are. Counter fields are answered as per-second rates with reset detection; gauge fields as window averages with their observed minimum and maximum. A core virtual node shares a server's host and answers `unavailable` instead of series. The point budget is for the whole answer, not for each device: it is divided by the devices the family resolves to, never below 32 points each, and a response carries at most 16384 points in total. `points` says how many it carries and `series_omitted` how many devices did not fit — ask for one device, or a shorter range, to see them. `family` also takes a comma-separated list (`family=cpu,mem,disk`), which answers every family named in one round trip: `{ node, from, to, local_only, finalized_through, families: { "cpu": <the single-family body>, … }, caps, gaps }`. The node is resolved and authorised once and one reader serves every family; `caps` and `gaps` describe the node rather than a family, so they are carried once above the map instead of inside each body, and `finalized_through` at the top is the oldest of the families'. The point budget applies to each family separately, exactly as it does to a single-family answer, so a list of seven families may carry seven times the points. `device` is applied only to the families that have a device dimension (disk, net, fs), and ignored for the rest. An unknown name refuses the whole request and says which one it was. Requires the `ReadNodeStats` permission in the node's project.

Read every node of a pool at one instant

One row per node the caller may see in the pool: CPU busy as a share of all its cores, memory used and installed, disk throughput and network throughput, each the newest point inside `[from, to)` — one chart window, so the table under a chart says what the pointed instant looked like on every machine. A node that reported nothing in the window is a row of nulls, not a missing row. Requires `ReadPool` and `ReadNodeStats` in the pool's project.

Read one metric family across a pool

One catalog family over a time range for every node of a pool, in one of three shapes. `totals` adds the nodes up at each window, which is what a counter's rate means for a fleet and what makes a latency distribution mergeable (sum the `http_latency` buckets). `distribution` gives the spread across nodes at each window — minimum, nearest-rank p10, median, p90 and maximum of the per-node values, computed from the exact per-node points, so it is a percentile across machines at one instant and never a percentile of percentiles. Within a node the family's devices are summed unless one is named. `app` selects an application's families (`proc_self`, `server`, `http`, `http_latency`); absent it is the host's own. A node that reported nothing in the window is not counted as a zero — every point says how many nodes were behind it. Requires `ReadPool` and `ReadNodeStats` in the pool's project.

Get an organization's address plan

Returns the org's allocatable and reserved prefixes and its allocated `/24` blocks. Requires the `ReadAddressPlan` permission (system operator).

Add an address-plan prefix

Adds an allocatable (default) or reserved IPv4 prefix to the org's address plan. Requires the `ManageAddressPlans` permission. Overlaps within this plan are rejected (422); overlaps with another org's plan are allowed and reported under `warnings`.

Remove an address-plan prefix

Removes an allocatable (default) or reserved IPv4 prefix from the org's address plan. Requires the `ManageAddressPlans` permission.

List a project's network

Returns the project's isolated network (VNI, subnets, members) as a list of zero or one entry. Requires the `ReadProject` permission.

List visible nodes

Returns every node in the pools the caller can see (via org or project membership), including liveness state, as a paginated envelope. Each node also carries `baking` (true for a pool-image builder) and `bake_phase` — `booting`, `installing`, `snapshotting`, `publishing`, or `null` for a node with no bake in flight. A builder not placed on a host yet also carries `waiting` — `{reason, message}`: its pool's park token (or `null` when the pool is not parked) and what it is waiting for, in words — which is `null` for every placed node. An online node of a `wireguard` provider whose agent registered no WireGuard key carries `waiting` with reason `mesh-key`: its apps are withheld until the agent is upgraded. Each node carries `agent_version`, `agent_os` and `agent_arch`: the build its agent last reported on connect, each `null` while it is unknown (an agent that predates the report, or one not connected since the node was created or rebuilt). `agent_upgrade` is `{to, phase, since}` while an agent upgrade is in flight and `agent_upgrade_last` is `{to, outcome, reason, at}` for the last one that closed, each `null` when there is none. A node whose agent is below the supported floor carries the `agent_below_floor` warning.

Read one node

Returns one node the caller can see, in the same shape the node listings carry — including its current price, the whole price history behind it, and `baking` / `bake_phase` (`booting`, `installing`, `snapshotting`, `publishing`, or `null`), and `waiting` (`{reason, message}` for a builder not placed on a host yet, or reason `mesh-key` for a node held for want of a WireGuard key; otherwise `null`), and `agent_version` / `agent_os` / `agent_arch` (the build its agent last reported on connect, each `null` while unknown), and `agent_upgrade` / `agent_upgrade_last` (the upgrade in flight and the last one closed, each `null` when there is none).

Get a node's audit history

Returns the node aggregate's ordered event log as a paginated envelope; each entry carries the event type, sequence, and decoded payload. Requires the `ReadNode` permission in the node's project.

Execute a bounded command on a node

Runs an executable with exact arguments, without a TTY, as the node agent account. For shell expressions use sh -c on Linux or powershell.exe -Command on Windows. Returns stdout, stderr, exit_code, signal, timed_out and truncated. Input ends with EOF. Runtime is limited to 45 seconds and retained output to 8192 bytes combined; excess output is drained and discarded. A timeout or lost connection cancels the process. Commands are never retried. Requires terminal_attach permission and MCP orc:write scope. Each call starts a new process; working directory and environment changes do not persist between calls.

Stream a node's logs

Server-Sent Events stream of a node's durable logs. Replays retained rows then live-tails. Requires the `ReadNodeLogs` permission in the node's project. Debug-level records are returned only to callers that also hold `read_node_debug_logs` at zone scope (the system organization's owners and members); for anyone else `debug=true` is ignored and the stream carries info and above. `Last-Event-ID` resumes while rows are retained.

List the App data restore points a node produced

Returns the retained restore points captured by this node, newest first within each app's lineage, optionally filtered by slot and app. These are the pool listing's rows narrowed to this node; `bytes` and `files` are what the node declared for that point's contents, and `reference` is the artifact `orc pull` takes (its `tag` within the pool's App-data repository). Requires the `ReadPool` permission in the node's project. Taking a point's contents — downloading it, or being given the key that opens a pulled one — is a separate permission and a separate route, and no key is ever part of this answer.