API reference

rupu cp serve serves a JSON API under /api/*; the web UI is built entirely on it, and so are peer control planes that drive this host remotely. This page lists every route. The operator guide is Control plane; customer scoping, attribution and the launch preview are covered in more depth in Customers.

Request and response bodies are named by their Rust type where they are large; those types live in crates/rupu-cp/src/api/ (and rupu_orchestrator / rupu_transcript for events). The API is versioned with the binary: a feature a peer needs is advertised in GET /api/host/info → features.

For agents rather than apps, rupu cp serve also serves every route here as an MCP tool at /mcp (plus a wait long-poll); see MCP & tools.

Conventions

Authentication

Started without --token, the API is open. Started with --token <t>, every /api/* route requires the token, either as the header

Authorization: Bearer <t>

or as the browser cookie rupu_cp_token_<port>. A page load (any non-/api path) with ?token=<t> sets that cookie and answers 303 to the same URL without the parameter. The cookie's value is derived from the token, not the token, and is not accepted as a bearer. A cookie-authenticated request that isn't GET/HEAD/OPTIONS must also send an Origin matching the Host it was sent to, or it is a 403. Comparisons are constant time. A missing or wrong token is a 401 with the standard {"error": ...} body. ?token= is ignored on /api paths. /healthz, the static UI and /api/node/connect (which authenticates nodes with their own enrollment token) are outside the check. See Control plane → Authentication.

curl -s -H "Authorization: Bearer $CP_TOKEN" \
  "http://127.0.0.1:7878/api/runs?limit=5"

Errors

Handler errors are JSON:

{ "error": "run 01JEXAMPLE0000000000000000 not found" }

A few endpoints add fields (a bad findings query adds token, code, start, end; deleting a customer with projects adds projects; a failed artifact pull is { "unavailable": "<reason>" }). A malformed query string or JSON body is rejected by the framework before the handler runs, with a plain-text 400/415/422. An unknown /api/... path is a JSON 404 (no API route for /api/...), never the web app.

Path parameters (:id, :name, :ws_id, …) are single plain path components. Before any handler runs, a request is a 400 if any /api/* path segment percent-decodes to something that can't be one: ., .. or a name starting with . or -, an encoded / or \, an encoded ? or #, a control character, or an invalid escape. Handlers validate their own parameters on top of that.

Common query parameters

• host=<id> — act on a registered remote host instead of this one. local is this host. An unknown id is a 404. On list endpoints an absent host fans out to every host and merges newest-first; per-host failures follow the 501/502 rules above. Remote errors follow one table.
• customer=<slug>|none — narrow to a customer's runs (by recorded attribution) or to projects currently assigned to it. See Customers.
• offset, limit — paging. limit defaults to 20 and is clamped to 1–200.
• since, until — RFC 3339 timestamps bounding a list by start time.
• scope_kind=global|project, scope_id=<ws_id> — pin a definition to the global layer or one project's .rupu/.
• q=<query> — the one-line list query (the findings grammar: status:failed,cancelled -workflow:nightly since:7d "two words") on /api/runs/workflows, /api/runs/agents, /api/sessions, /api/projects/:ws_id/{runs,sessions} and /api/events. See List queries.
• facets=1 — on the same lists, answer {rows, facets, facets_partial} instead of the bare array.

Remote host errors

One table holds for every ?host=<remote> call:

A list's "not found" is a 502 because a reachable host answering a list route with 404 is broken, not empty. A 404 that names the host (host <id> not found) always means the id isn't registered.

List queries

A q term's values OR, terms AND, - negates, a bare word searches the list's text fields; comparisons are case-insensitive. It filters before offset/limit cut the page and ANDs with the list's other parameters (lifecycle, scope, since, until, customer). Remote hosts' rows are filtered on this server, reading past peer page clamps, as customer is: a host whose rows can't report a field the query names (no customer key: an old peer) is a 501 on ?host=<it>, and left out of a fan-out and named in X-Rupu-Hosts-Without-Customer (the customer field) or X-Rupu-Hosts-Unfilterable (<host>:<field>, any other field). A q that doesn't parse is a 400 {error, token, code, start, end} (token index and char span). Time fields (since, until) take 30m, 12h, 7d, 2w (back from now, at most 10000 years), a UTC date (2026-10-01, the whole day) or an RFC 3339 time. Each list's fields, with their kind, values and match mode, are in crates/rupu-cp/tests/fixtures/list_query/<list>.fields.json, and Query help serves them.

is:archived on /api/runs/workflows lists the archive instead (rows carry archived: true); it is local only: a remote host is a 501, and on a fan-out each remote host is named <host>:is. On /api/sessions it reads each session's scope and asks remote hosts for their archived sessions; scope= still works.

With facets=1, facets counts each facet field's values (field → value → rows) over the list's scope before q. facets_partial: true when some remote host's rows were read one page only (an unfiltered workflow-run listing), so its counts cover that page.

Mutations are recorded, not done

Runs are detached processes. A control endpoint's 200 means the request was recorded (a marker, a decision, a signal sent) — watch the run's status on a stream to see it take effect.

Server-sent events

Four endpoints stream text/event-stream:

Every frame is an unnamed data: line carrying one JSON event. On the one-run and transcript streams it also carries an id: — the event's line number in its file — and the stream ends with a named end event (see below). The firehose has neither.

• Run streams carry rupu_orchestrator::executor::Event, internally tagged: {"type": "step_started", ...}. dispatch_started / dispatch_completed (a step's agent started or finished a child run) carry the child's kind: subagent, agent or workflow. Lines written before kind existed read as subagent.
• Transcript streams carry rupu_transcript::Event, adjacently tagged: {"type": "...", "data": {...}} (see Transcript schema).

id: 2
data: {"type":"step_started","run_id":"01JEXAMPLE...","step_id":"triage",...}

: keep-alive

id: 9
data: {"type":"run_completed",...}

event: end
data: {}

Behaviour worth knowing:

• Replay, then resume. A stream sends the file's history from the start, then tails it (polled every 250 ms). On a one-run or transcript stream an event's id is its line number in the file (every line counts, so ids don't shift across rupu versions), and Last-Event-ID resumes after it instead of replaying. Browsers' EventSource sends the header on its own when it reconnects. If the file is rewritten (a mirror cache refilled from byte zero), the stream doesn't resend what it already sent.
• Keep-alive is a comment line every 15 s.
• Ending. A one-run stream ends once the run is over: its last event is a run_completed / run_failed, nothing follows it for 2 s, and the run is settled (terminal record, no gate-reject cleanup pending, no live runner). An earlier terminal event in the file (a failed attempt that was retried, a gate reject followed by its on_reject chain) never ends it. Then one event: end frame with retry: 15000 follows and the connection closes: close your EventSource on it, or keep it and it reconnects 15 s later with Last-Event-ID — getting end again, or the events of a retry (the web run page does this). A transcript stream ends with end after run_complete. The firehose never ends.
• Firehose scope. The firehose follows runs in the run store — workflows and autoflows. Standalone agent runs and session turns never appear on it. It attaches to active runs at start, then to any new run id it sees (checked once a second), and drops a run's tail 30 s after it finishes.
• Remote hosts. With host=<remote>, the remote's run stream is passed through; /api/events/stream then requires run. Last-Event-ID reaches it: a mirror-backed host (SSH, tunnel, bucket) resumes from the coordinator's mirror, and an HTTP host gets the header forwarded. An HTTP host running an older rupu ignores it and replays without ids, as before.
• Sessions and run lists have no stream; the UI polls them.

curl -N -H "Authorization: Bearer $CP_TOKEN" \
  "http://127.0.0.1:7878/api/events/stream?run=01JEXAMPLE0000000000000000"

Runs

Run control

All take host. Locally they return the updated run detail plus host_id; remotely {ok, host_id}. Their JSON bodies are optional: an empty body means none, and a body that isn't the expected JSON is a 400.

Run views

Events and transcripts

Sessions

Start a session with POST /api/agents/:name/session.

Messages

The operator's side of a run's message space (see Messaging): read what was said in it, and send into it as the operator, the way rupu message list|send does. The same three endpoints exist under each root that has a space:

An id is served only under the prefix its kind names: a session id under /api/runs is a 404, as is an unknown id.

POST /api/agentiflows/:id/steer is kept as an alias. Without stop it is exactly POST /api/agentiflows/:id/messages {to: "lead", body: message, urgent: now}, answered the same way. With stop: true it queues a graceful stop on the run's control queue instead (see Agentiflows).

The stream replays the log from the start, then tails it, as the other streams do. Each frame is an unnamed data: line with an id: (the line's number in the log; Last-Event-ID resumes after it). The data is one of:

• {"t": "msg", …}: a message in the shape GET returns, with seen: [].
• {"t": "seen", "id", "by", "turn", "at"}: a receipt for message id.

The stream stays open after the run ends (a finished run's space can still be read); close it when you're done.

curl -X POST -H "Authorization: Bearer $CP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"to": "step:review", "body": "skip the vendored code", "urgent": true}' \
  "http://127.0.0.1:7878/api/runs/run_01JEXAMPLE0000000000000000/messages"
# 202 {"id":"msg_01JEXAMPLE...","delivery":{"resolved":["heron#2"]}}

Remote hosts

With host=<id>, GET and POST go to that host. The stream does not.

A host that can't be reached is a 502, as for any remote read.

Launch, agents and workflows

Launches return as soon as the detached process is spawned; all are 501 without rupu cp serve.

curl -s -X POST -H "Authorization: Bearer $CP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"inputs":{"pr":"42"},"mode":"readonly"}' \
  http://127.0.0.1:7878/api/workflows/review-pr/run
# {"run_id":"01JEXAMPLE0000000000000000","host_id":"local"}

Skills

Installed Agent Skills. The reads take the global layer and, with ws_id, that project's layer (.rupu/skills in the workspace; none when the project's .rupu is the global dir). An unknown ws_id is a 404.

The writes run what rupu skill install|update|validate run, through the same rupu_skills functions (an install is staged, validated and renamed in by install_from). They are local only: a host other than local is 501. Install and update need cp serve (501 otherwise), which provides the git fetch.

Hosts receive the skills of a placed unit through two more routes, behind the agent.skill_bundle feature in /api/host/info (see Skills on placed units). They write only to <RUPU_HOME>/cache/skills.

SkillsResponse is {skills: [SkillRow], warnings: [string]}. A layer that can't be read is left out of skills and named in warnings ("project layer: <path>: <error>"); the response is still 200. A row:

SkillDetail is the row's fields plus path, license, compatibility, allowed_tools, mapped_tools (the rupu tools allowed-tools maps to; informational, never a grant), disable_model_invocation, metadata, files (relative to the skill, without SKILL.md), content_hash (short), body (SKILL.md without its frontmatter), source_record (the install record as written) and source_error (why the record couldn't be read). The fields that need a loaded skill are empty for an invalid one. An install record is read only when it is a regular file of at most 64 KiB, and never through a symlinked project skills/.

Autoflows

Every autoflow read and write above except the definitions list and enable/disable runs on this control plane's own RUPU_HOME only: a host other than local is a 501. They answer with the JSON report the matching CLI command prints under --format json, from the same library (rupu-autoflow), on any control plane. Autoflows are visible from the directory rupu cp serve started in, as from the CLI's working directory. Starting a cycle (POST /api/autoflows/:name/run) needs rupu cp serve (501 otherwise), which spawns it; a write that isn't a dry run also needs it as the write gate. GET /api/autoflows/:name never shadows the literal claims, doctor, wakes and explain routes.

Cron and maintenance

Local host only (host other than local → 501). They read the global layer and the project layer of the directory rupu cp serve started in, as its cron loop does. The listings and every prune work on any control plane; the tick needs rupu cp serve (501 otherwise), which runs the workflows.

Findings

Query language, tags and report export are covered in depth in Findings.

Coverage and assets

All local-only. ws_id is optional; without it the first workspace containing the target is used.

Query help

What each list's q takes, and a check of a query without running it. The registries are the ones the lists filter with, so the answer is the list's own; the field shapes are the ones crates/rupu-cp/tests/fixtures/list_query/ and crates/rupu-coverage/tests/fixtures/finding_query/fields.json pin. :list is findings, workflow_runs, agent_runs, sessions, autoflow_runs or events; any other is a 404 naming them.

curl -s -X POST -H "Authorization: Bearer $CP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"q":"sev>=high -tag:noise"}' http://127.0.0.1:7878/api/query/findings/check
# {"ok":true,"terms":[{"neg":false,"key":"severity","op":"ge","values":["high"]},{"neg":true,"key":"tag","op":"eq","values":["noise"]}]}

Usage and dashboard

since / until are RFC 3339 (default: the last 30 days). A value that doesn't parse is a 400.

Endpoints that take customer add an X-Rupu-Hosts-Without-Customer response header naming hosts whose rows couldn't be attributed — see Customers → Remote hosts.

Netflow

Netflow reads take from / to (inclusive RFC 3339) and comma-separated dimension filters workflow, origin, org and host. Here host filters by remote endpoint (host:port), not by registered rupu host. Each dimension has an exclusion list too, not_workflow, not_origin, not_org and not_host: a flow whose key is listed is left out. An explorer response built with exclusions says exclusions_applied: true; for a run on an HTTP host older than the exclusions, the explorer answers 501 rather than relay an unfiltered view.

Projects and code

An unknown ws_id is a 404 on every route except the list.

Stock fleet, project init and engagement profiles

What rupu fleet list|install, rupu init and the run assembler's profile registry do, through the same functions (rupu_templates, rupu_coverage::profile). All local only: a host other than local is 501. The writes need cp serve (501 otherwise).

Hosts, workers and fleet

Workspace sync (host-internal)

A coordinator placing a run on an HTTP host ships the workspace, runs there, and pulls back the diff. The web UI never calls these.

Config, models and tools

MCP

rupu cp serve mounts an MCP endpoint at /mcp (streamable HTTP, POST only) beside the web UI and /api, behind the same bearer token and an Origin/Host guard. It serves one operator tool per CP route (the routes on this page, minus the SSE streams, the host-to-host transfer routes, the node WebSocket, /healthz, /api/fs/browse and POST /mcp itself), a wait long-poll in place of the streams, and the tool catalog GET /api/tools lists. rupu cp serve --no-web serves /api + /mcp without the UI, --no-mcp the UI + /api without it. Setup, tool names, resources and prompts are on MCP & tools.

SCM, repos and auth status

What rupu scm accounts / scm bind, rupu repos tracked / attach / prefer / forget and rupu auth status show and write. Local host only: ?host= other than local is a 501 that says so. The SCM endpoints read and write the global config (where rupu scm bind writes). No answer carries any part of a credential: not a token, an API key or a refresh token, and a tracked repo's origin urls (which can embed one) are never returned. Logging in stays rupu auth login. A global config that does not parse is a 500 naming the file, never an answer built from defaults.

Customers

Writes need a cp serve deployment and answer 501 otherwise. The config layer and the rupu customer CLI are in Customers.

A customer's tint is its color for both themes when set, else a light/dark pair derived from the slug, so clients never invent colors. default_account is {account, locked_by, inherited}: the provider account the customer's runs default to over global + its layer (inherited: true when the value is the global one); null when nothing sets one or the layer does not resolve (layer_error says why on the detail). The detail's projects[] are the customer's current projects; each row's usage, run_count and last_active cover only this customer's work in that project over the same range as rollup. Rollups are computed in one pass over the run store: standalone agent runs and session turns add spend and activity, never run_count, and each run is priced with the pricing of the customer it is attributed to. A customer whose layer does not resolve is still listed, with default_account: null and layer_error, and its work is priced at the global rates — every usage summary that includes such work carries pricing_error naming the customer.

?customer=<slug>|none

<slug> selects one customer's work; none selects work with no customer. A malformed slug is 400. A slug no customer carries is not an error — it matches nothing. A run records the customer it ran under at launch, tri-state on disk: a slug, an explicit null (recorded no customer, even if the project has been assigned since) or no key at all (a legacy record, attributed to the project's current assignment and marked customer_derived: true). Findings and projects record no customer — they follow the project's current assignment.

Remote hosts

A remote host's run and session rows are filtered on the coordinator by their customer key, reading page after page past the peer's clamp. If any row lacks the key (a peer older than customers, a mirror holding a worker's legacy runs, or rows the peer could not attribute), the host "can't report a customer for every run": a single-host request (?host=<id>) answers 501, and the fan-out skips the host and names it in the X-Rupu-Hosts-Without-Customer response header (comma-separated host ids). It is never counted as zero. Aggregates (/api/usage, /api/dashboard) are local-only under a filter: ?host=<remote>&customer=… is 501, and the fan-out reports each remote host unavailable rather than counting it. A mirrored legacy run is named in a hosts_without_customer array on /api/usage, /api/dashboard and each customer row's rollup.

An unreadable project assignment (workspaces/<id>.customer) fails closed: every filtered request and every count, rollup or price answers 500 naming the workspace and the file to repair. An unfiltered run / session list does not fail: the affected rows omit the customer / customer_derived keys and a warning goes to the server log.

Launch preview

POST /api/launch/preview says what a launch would authenticate as, before it runs. Body: exactly one of workflow / agent (400 otherwise), plus the launcher's working_dir or scope_kind / scope_id (mutually exclusive, as on the launch routes; with neither, the server's cwd) and an echoed host. It resolves exactly like a launch: a project assigned to a customer that no longer exists, or a config that does not load, is 409, as is an agent file that does not load (one malformed file fails the loader for every agent). 404 for an unknown workflow, or an unknown agent on an agent launch. A name containing /, \ or .. (or empty) is 400 before any file is read.

Response {customer, accounts, warnings, host?}: customer is the row reference (slug, name, tint, archived) or null; accounts are {role: provider|fallback|scm, account, kind, auth_mode, agents[], source} entries, source saying where each choice came from ("agent frontmatter", "customer default", "global default · locked", "rule owner = acme-corp", …); warnings are resolver warnings, a workflow step's agent that was not found, an origin that is not a github.com / gitlab.com remote, an ambiguous or unresolvable SCM account and, for a non-local host, that the preview resolves against the machine running the control plane. The SCM candidates are only the accounts the config declares for the repo's platform that have a stored credential — the same set rupu scm accounts shows; provider credentials are not probed here.

Agentiflows

Local host only, except the message space (Messages), which takes host. The writes answer a remote ?host= with a 501. The concept is on Agentiflows.

Rounds and children are read with GET /api/agentiflows/:id. The round events in events carry, beyond the round number and counts: started_at; decision (the round's own last assistant reply, cut on a word boundary at 600 characters with … appended; omitted when the round produced no reply text, so a failed round never shows an earlier round's decision); goals ([{id, met, current}] as the round started, so the state after round N is round N+1's goals, and after the last round the record's goals); and warnings (omitted when empty). Each units row carries round and generated like a child. A run recorded before these fields shows less, never a guess: no decision, no goals, and units without a round are placed by inference and marked so by clients.

Board

BoardView is the wire shape of GET /api/agentiflows/:id/board, GET /api/runs/:id/board, the hidden rupu __board <id> and the MCP tools agentiflows.board / runs.board:

{
  "claims": [{"key": "…", "key_known": true, "owner": "heron#2", "acquired_at": "…",
              "lease_expires_at": "…", "ended_at": null, "state": "held"}],
  "directives": [{"id": "…", "author": "lead", "ts": "…", "body": "…", "addressed_to": "role:recon",
                  "retracted": false}],
  "journal": true
}

claims is every acquisition the space's claim journal (board/claims.jsonl, see Messaging) recorded, released and expired ones included. state is held, released or expired; ended_at is when a released or expired claim ended. directives keeps retracted ones, with retracted and, when the retraction recorded a time, retracted_at; addressed_to and retracted_at are omitted (not null) when absent — a directive to everyone has no addressed_to. journal is false for a space written before the journal: claims then holds only the claims live now, each held with key_known: false (its raw key was never recorded, so key is the claim file's stem). An empty or absent board is empty lists, not an error.

GET /api/runs/:id/board serves a workflow run or standalone run (a run_… id; anything else is a 404), with host. A remote host is asked over HTTP when its /api/host/info lists the run.board feature (otherwise a 501, "upgrade rupu there"), over SSH through rupu __board <id> after the same rupu __features gate as run.messages, and a tunnel or bucket host is a 501.

Agentiflow definitions

The <name>.yaml files rupu agentiflow run <name> loads: the global layer (<RUPU_HOME>/agentiflows/, beside the run directories, which are never read as definitions) and each registered project's .rupu/agentiflows/. A project definition shadows a same-named global one, as it does for the CLI. The scope_kind/scope_id selector works as it does for workflows. Local only: every route answers ?host=<remote> with a 501.

Node tunnel

GET /api/node/connect upgrades to a WebSocket for rupu node peers that dial home (a tunnel host). It is host-internal and sits outside the bearer check; it authenticates with the node's own enrollment token:

1. Enroll the node with POST /api/hosts/node, which returns a one-time token and the rupu node --cp-url ws://<cp>/api/node/connect --token … --node-id … command to run on the node. Only the token's hash is stored.
2. Within 10 s of connecting, the node sends a Hello frame with its node id, token, capabilities and version. An unknown node or bad token closes the socket.
3. The CP answers Welcome with its own capabilities, then pings every 30 s. The node streams run artifacts (transcripts, coverage) and finished-run notices back over the same socket, and serves artifact pulls on request.

A newer connection for the same node replaces an older one. Frames are JSON text messages; the shapes are rupu-cp's node::protocol::Frame.

Health

curl -si http://127.0.0.1:7878/healthz
# HTTP/1.1 200 OK
# x-rupu-pid: 41207
# x-rupu-version: 0.82.0
#
# ok