HTTP API

Everything RoboVAST does remotely goes through one HTTP service (robovast.service.app, FastAPI). The CLI, the web UI and the MCP server are all clients of it: HTTPTransport (robovast.service.http_client) is a method-per-route mirror of this table, and the service implements the same interface in process. So the routes below are not a second API — they are the one interface RobovastInterface describes, over HTTP.

The service also serves its own OpenAPI at /docs (and /openapi.json), which is authoritative for request and response schemas, and mounts the MCP server itself at /mcp (see MCP Server) — all on the one port. This page covers what /docs cannot: the conventions the route table assumes.

Who may call it

Every request needs the shared access token — there is no unauthenticated mode. A browser exchanges it for a session cookie at /login; the CLI and MCP send Authorization: Bearer. vast cluster setup mints the token and vast service token prints it; a published service sits behind an Ingress with TLS, and a one-node one is reached over a port-forward on 127.0.0.1. See Deployment Modes and Access for the boundary and vast login.

The gate is ASGI middleware (robovast.service.auth.AuthMiddleware), not a FastAPI dependency, so a new route is covered automatically: a dependency would miss the mounted /mcp sub-app, which does not run the parent app’s dependencies, and BaseHTTPMiddleware would buffer the streaming responses. It resolves a Principal rather than a boolean — read identity from that rather than re-parsing headers, so exchanging the shared secret for an identity provider replaces one resolver instead of every route.

A scoped token is the second kind of credential the gate accepts, and the only one a pod is ever given. It is <scope>.<hmac> – an HMAC of the scope under the shared secret (robovast.service.auth.scoped_token()) – and it reaches exactly the data-plane routes of the one campaign or staged slot the scope names (scope_allows()); anything else is a 403, distinct from the 401 an unauthenticated caller gets so the pod is not sent to log in with a token that already proved itself. It needs no registry: every process holding the secret verifies it, a restart forgets nothing, and a scope stops mattering the moment nothing answers for it. Handing a pod the shared secret instead would let any container in the cluster start campaigns.

Two consequences show up in the table. GET /version redacts results_root and sources_root for any caller that is not on the same machine, because those are filesystem paths only useful — and only safe — to one that is; a forwarded request counts as remote, since behind a proxy the peer address is the proxy. And the file routes serve real paths on the service host, which is the point of the address space below.

Addressing files

File routes are not one resource per scope; they are one address space, which that section documents in full. The parts that matter when reading the route table:

  • /results/<campaign_id>/<path> is campaign output, and is read-only by registration — no write route exists, so a PUT or DELETE there is a router-level 405, not a permission check that could be got wrong.

  • /sources/<workspace_id>/<path> is editable project input: GET, PUT, POST (substring edit) and DELETE.

  • A trailing / means “the directory”, and listings page server-side.

Large uploads take the side channel instead: POST /uploads grants a token, and PUT /uploads/{token} streams the bytes.

The data plane is the third namespace, /data: every route that moves a campaign’s or a staged slot’s bytes as one tar stream. GET /data/campaigns/{id}/archive is the campaign as a tar.gz (narrowed by stage, skip_bags and batch_jobs to what a postprocessing pod reads, and a plain tar with uncompressed); GET .../inputs is what a job pod extracts into its /config, with the campaign’s _config/ and _transient/ flattened, only the named jobs’ own documents (job=<tag>, required) taken from the per-job ones, and a cell’s own files (config_file=<config>:<rel>) landing on top; PUT .../outputs takes a pod’s output tree into the campaign, last writer wins, with what the driver owns – the campaign’s own store, its logs – refused per member and named in the reply; and GET/PUT /data/staged/{slot} move the scratch trees the service stages for a build or exec pod. Every stream a pod reads is a plain tar, and an upload may be plain or gzipped: the reader detects it. These are control routes, not writes under /results, so that space keeps having no write verb at all. Streamed both ways, never buffered: a download is tarred as it is read and an upload is extracted as it arrives, through a bounded queue, so a slow disk holds the socket back rather than the body piling up in memory. In the cluster Deployment they are answered by their own process behind the front (Deployment Modes and Access); a vast serve started by hand mounts them into its one app, at the same paths.

A campaign archive has its own channel rather than an address in that space, because /sources needs workspaces configured (a 501 otherwise) and an archive is not project input, while /results is read-only by registration and punching a write into it would cost exactly the property that section describes. So: POST /campaigns/archives grants a token, PUT /campaigns/archives/{token} streams the bytes — streamed to disk, not buffered, unlike the /uploads PUT whose payload is a .vast — and it answers with where they landed. It stops there. POST /campaigns/import is the import, for that upload and for a path put on the host by any other means, so the operation has one implementation rather than one per entry point; an archive the service staged is removed once imported, a path the caller named is not.

An upload that was never imported is not removed when the import refuses it: the answer to the commonest refusal — a campaign of that id is already here — is to import the same staged archive again with force, and cleaning up on refusal would turn that retry into a second multi-gigabyte upload. They are swept by age instead, on the next grant. Age rather than liveness because the grant is consumed when the PUT begins, so an unreferenced staging file cannot be told apart from one still arriving.

Status codes

Handlers delegate to the interface and map its exceptions in one place (_guard), so the meaning of a status is uniform across every route:

Code

Meaning

400

ValueError — a malformed or rejected argument (an unknown backend, a path escaping its namespace, a non-SELECT query).

404

KeyError — no such campaign, workspace, build or file.

409

RuntimeError — the request conflicts with current state (stopping a campaign that is not running; importing over a campaign that is already here, or one that is busy with another operation).

422

A notebook or visualization failed to render.

501

UnsupportedOperation — the operation exists and the implementation answering does not offer it. The detail is one sentence naming the operation and the implementation, so it cannot be mistaken for bad input, a conflict, or a bug. Also: workspaces are not configured on this service.

503

A dependency did not answer, so the request could not be attempted: the object store, the index, or the exec path into a container. Worth retrying, unlike the codes above.

507

The service is out of disk space, or low enough that it declines new work (see Keeping free space). Never reported as bad input or a conflict: the request itself was fine, and is worth retrying once space is freed.

A call that acts on several things answers per thing, not with one status. POST /campaigns/delete takes {"campaign_ids": [...]} and returns 200 with one result per id — its outcome (deleted, not_found, partial, running, invalid) and its own message — because a running campaign among the ids is a fact about that id, and a 409 for the whole call would hide that the others were deleted. Only a request naming no campaign is refused as a whole (422). The single-campaign DELETE /campaigns/{id} keeps the codes above: 400 for an id that is not a campaign id, 409 for a running campaign.

A refusal whose class a caller must act on rather than print also carries an x-robovast-error header naming that class: exec_path_unavailable, for a deployment where no command can be run in a container at all, and unsupported_operation, for an operation this service does not offer (a client neither retries it nor blames its input). The exception type is what an HTTP boundary drops, and a client that has to behave differently (report the deployment rather than the image, degrade a check to “unchecked”) would otherwise have to match on the sentence, which then nobody may reword. ServiceError.code carries it; the body stays FastAPI’s {"detail": ...} for every refusal, coded or not.

Streaming

Five routes stream instead of returning a body. The two .../stream log routes and GET /campaigns/events are server-sent events; they are resumable, so a client that drops sends Last-Event-ID and continues from the line after the one it last saw rather than replaying the whole log. GET /data/campaigns/{id}/archive streams a tar.gz of the campaign, tarred from the campaign directory as it is read. Every service answers it: refusing because “the results are already on this host’s filesystem” would assert something true of a caller on that host and false of everyone else. GET /workspaces/{id}/archive is the same for a workspace’s project files, under a single top-level directory. It is a control-plane route rather than a data one, because a workspace is not on the results volume the data routes serve.

Every tick of an SSE stream that had nothing to report sends a heartbeat event. It is a named event rather than the SSE comment such keepalives usually are, because a comment is invisible to EventSource — it holds proxies open and tells the client nothing. Without a frame the client can see, a stream that is merely quiet is indistinguishable from one whose socket died in a suspended laptop or a torn-down kubectl port-forward: no error is raised, readyState stays OPEN, and no further byte ever arrives. A client should therefore treat a gap of several heartbeats as a dead connection and open a new EventSource; the web UI does exactly that (see Web UI).

What may ride on a polled payload

GET /campaigns/{id}/status and GET /campaigns/events are hot fan-out payloads, and that governs what may be put on them. The web UI renders every campaign in the list as a card; each card polls the status every 1.5 seconds, and the list stream re-lists every campaign once a second for as long as any tab is open. So the cost of a field there is multiplied by campaigns on screen, by polls, and by open tabs — and served over HTTP/2, where no connection limit throttles a page-load burst the way it once did.

Four tiers, and the question to ask of any new data is which one it is in:

Kind

Example

Transport

An origin, for anything time-dependent

phase_since, batch_since, search_since

on the polled Status, written once

Bounded state, and cursors

phase, run counters, batches_done, best_objective

on the polled Status, written when it changes

A series, read by whoever is looking at it

a search’s per-batch objective trajectory

its own route, fetched lazily, keyed on a cursor

High-rate telemetry from a running run

a future live run view

its own stream, per run

The series row is the one that gets this wrong. Status carried a batch_history — one entry per batch, growing for the whole run — that nothing ever read, on the payload polled most often in the system. It was replaced by GET /campaigns/{id}/search/history, which is requested only while something is displaying it and re-requested only when batches_done (a single integer on the status) moves. A series is almost never so small that it belongs on the status; if it grows with batches, runs, or time, it does not.

GET /admin/events is the series row done the way that row prescribes: its own cursor-keyed route, requested by whatever is displaying it and resumed from next_seq, rather than a field on a payload every open tab re-fetches once a second.

It is also the one durable thing this service keeps about itself. /admin/log is this process’s recent stderr and dies with it, and the usage samples say the same about themselves — both answer “what is it doing now”. The events worth keeping are the ones a restart destroys, which is why they are in SQLite on a mounted volume rather than a third ring.

What it records is what this service otherwise says once and forgets. Every refusal a client was sent — composed in the request that refused it, rendered once, and then gone; recorded in the exception handlers, so a route that raises its own error, a request that never parsed, and a failure nobody caught are all in it rather than only the calls that happen to be wrapped. And each campaign’s lifecycle — started, finished, failed, stopped, uploaded, postprocessed — which otherwise reaches a phone over ntfy and a tab as a toast, neither of which anybody can read back. What is not in it: successful requests, so it stays a record of what happened and what would not rather than a request trace; a URL matching no route, which is a caller’s mistake about the address space and unbounded from anything that scans; and the hourly heartbeat, which says a campaign is alive now and is worthless once it is over.

Identical refusals inside a one-minute window collapse to one row carrying repeated: a panel polling an endpoint that cannot answer it would otherwise push a month of everything else past the log’s row bound within the hour.

GET /admin/mcp-tools, GET /admin/mcp-calls and GET /admin/mcp-calls.csv follow the same row for the MCP surface: what the tools were asked and what they answered, its own routes, requested by the panel displaying them and never carried on a polled payload. The ranking is an aggregate over the call log rather than a counter maintained beside it, so the two cannot drift; the CSV is the same rows as a download.

Their record lives in the central index rather than in events.db, which is the one place these depart from the events above: the rows carry a truncated copy of each call’s arguments and answer, so they are bulky and they age out (30 days, or 200 000 calls, whichever bites first), where the event log’s whole point is that it is small and durable. Both bounds are reported on the response, because a reader told “a month” during a burst that emptied it in a day would be told a wrong thing. An unreachable index is reported as status rather than as an empty list, for the same reason: “nothing was called” and “the record cannot be read” are different answers.

A page of /admin/mcp-calls reports the same way. It carries total, truncated and the limit/offset it was actually read with, because a page that reported none of them read as the whole record — and beside a ranking summarizing a month, a page holding an afternoon is a disagreement nothing announced. offset walks the rest. The CSV export is bounded only by what is retained, since it streams rather than being held in one response; a download has no field to report a bound in, so an export that did not reach the end of the record says so in the filename it arrives under, which is the part of a saved file a reader still has later.

Each row names its caller twice, because the two answer different questions. actor is the resolved principal: the name it gave and the source it authenticated by. session is "<client>/<session>" as the transport reports them, which is what separates two agents sharing one token. Either is empty where the transport resolves none, which is absent rather than anonymous.

The origin row is the cheapest tier and the one most often missed. A value that is a pure function of wall-clock plus one stored origin is transported as the origin, never as the value: the reader already has a clock. A time budget’s elapsed seconds is the case that established this. Its current comes from stop.progress(), which the controller calls once per batch, so on the wire it steps per round rather than ticking — and the obvious fix, having the progress poller rewrite it every few seconds, is wrong twice over. It pays for the value on every poll forever, and it breaks stall detection: ControllerState._progress_signal includes each budget row’s current, so a row rewritten from wall-clock advances the progress signal continuously and no time-budgeted search can ever be reported stalled again. That is the same trap the signal already avoids by not being updated_at. What ships instead is search_since, published once, with every reader deriving elapsed through budget_positions (and its TS mirror budgetPosition).

Hence the invariant behind it, which is not about transport at all: a derived value never enters the progress signal. That tuple may contain only facts whose change is evidence the campaign advanced. Wall clock advancing is not one.

Two worked examples of the tiers, for the search criteria specifically. A criterion’s comparison sense is tier one — static config, written once, never changing — and is on the status as BudgetItem.op for exactly that reason: without it no reader can render a stopping row correctly, and a bare current / limit pair silently asserts a >= the criterion may not use.

A strategy’s report().extra is tier two’s opposite: an open dict of unbounded size (it carries elites, measure_names, best_elite), so putting it on the status to surface a QD coverage figure would recreate batch_history exactly. It belongs on a route keyed on batches_done, like the trajectory above.

The telemetry row is deliberately a separate stream rather than another event type on /campaigns/events. A run’s telemetry and a campaign list have different lifetimes (per-run-while-viewing versus always-on), different rates, and different failure semantics; multiplexed together, one slow consumer stalls the other and a run view’s reconnects disturb the campaign list.

Paths are defined once

robovast.service.interface.Routes holds the canonical path strings and the builders for parameterized ones. Both the app and HTTPTransport use it so the two bindings cannot drift — a route renamed in one place is renamed for the client too.

The table below is generated from the running application, not maintained by hand: it is what the service registers, including routes added by installed endpoint plugins. A hand-written endpoint list is exactly how the retired synthetic run-file route came to look documented while matching no directory on disk.

Routes

meta

Method

Path

Description

GET

/healthz

Liveness probe: answers {"ok": true} as soon as the app is serving.

GET

/login

The browser’s way in: a password box, or a ready-made ?token= link.

POST

/login

Exchange the shared secret for a session cookie.

GET

/usage

Report the execution backend’s CPU/memory capacity + current usage.

GET

/usage/history

Recent CPU/memory use, sampled in this process since it started.

GET

/version

Report the implementation’s RoboVAST + API version (handshake).

authoring

Method

Path

Description

GET

/campaigns/{campaign_id}/panel_assets/{path:path}

Serve a user-authored custom panel’s bundle, staged into the campaign’s

GET

/config/schema

Return the .vast JSON Schema (ConfigV1.model_json_schema()).

GET

/panel_types/{name}/assets/{path:path}

Serve a package-provided run-view panel’s web asset (Module Federation remote).

GET

/variation_types

List the registered robovast.variation_types + their parameters.

GET

/variation_types/{name}/assets/{path:path}

Serve a variation plugin’s web-preview asset (Module Federation remote).

GET

/workspaces/{workspace_id}/scene

Is this project’s world compiled, and if not what is happening about it.

POST

/workspaces/{workspace_id}/scene/run

Compile this project’s world unless it is cached, and return at once.

GET

/workspaces/{workspace_id}/scene_assets/{path:path}

One file of a cached scene descriptor, for the config view’s loader.

workspaces

Method

Path

Description

GET

/workspaces

List workspaces, newest first.

POST

/workspaces

Create a workspace to author a project in.

DELETE

/workspaces/{workspace_id}

Delete a workspace and its inputs.

GET

/workspaces/{workspace_id}

Return one workspace.

GET

/workspaces/{workspace_id}/archive

Stream the workspace’s project files as a tar.gz.

POST

/workspaces/{workspace_id}/preview

Expand a workspace .vast into resolved configurations (no run).

POST

/workspaces/{workspace_id}/share

Upload the workspace’s archive to the configured share; return what landed.

POST

/workspaces/{workspace_id}/validate

Collect-all validation of a workspace .vast project.

POST

/workspaces/{workspace_id}/world

Describe the world this campaign’s simulator will load.

uploads

Method

Path

Description

POST

/uploads

Grant a one-time PUT for a /sources address.

PUT

/uploads/{token}

Redeem a one-time TTL token and store the raw body.

files

Method

Path

Description

GET

/results/{campaign_id}

A campaign root, with or without the trailing slash — always a listing.

GET

/results/{campaign_id}/{path:path}

A campaign’s outputs: one file’s bytes, its text page, or a directory listing.

GET

/sources/{workspace_id}

A workspace root, with or without the trailing slash — always a listing.

DELETE

/sources/{workspace_id}/{path:path}

Delete a file in a workspace. There is no such route under /results:

GET

/sources/{workspace_id}/{path:path}

A workspace’s authored inputs — same representations as /results.

POST

/sources/{workspace_id}/{path:path}

Replace a unique substring — the token-cheap validate→fix loop.

PUT

/sources/{workspace_id}/{path:path}

Write a .vast/.osc file inline (other types → the upload grant).

campaigns

Method

Path

Description

GET

/campaigns

The campaign listing: live campaigns first, then ordered by sort/order.

POST

/campaigns

Validate the workspace’s project and start a campaign; return its id.

POST

/campaigns/delete

Delete several campaigns, each as the single delete would. Not all-or-nothing: a running campaign or an id that is not a campaign id is that id’s outcome, not a refusal of the call, so the answer is 200 with one result per id – read each one.

GET

/campaigns/events

Server-sent events: the campaign list, pushed on every change.

DELETE

/campaigns/{campaign_id}

Permanently delete one campaign wholesale: its directory under the results

POST

/campaigns/{campaign_id}/job-exec

Run command inside a running job. Recorded against the run.

GET

/campaigns/{campaign_id}/job-log

Return a running job’s live log from byte offset onward.

GET

/campaigns/{campaign_id}/job-log/stream

Server-sent events: one job’s log, tailed live (Last-Event-ID resumes).

GET

/campaigns/{campaign_id}/job-state

What a running job is doing right now, from the run’s own tools.

POST

/campaigns/{campaign_id}/job-stop

Kill one running job; the rest of the campaign keeps going.

GET

/campaigns/{campaign_id}/jobs

List the campaign’s current-batch jobs (live) plus aggregate counts.

GET

/campaigns/{campaign_id}/logs

Return the campaign’s controller.log from byte offset onward.

GET

/campaigns/{campaign_id}/logs/stream

Server-sent events: a campaign’s controller log, tailed live. Resumable —

POST

/campaigns/{campaign_id}/retrigger

Launch a new campaign from an existing one’s frozen config and pinned image. The source campaign is not modified. Refused (400) when the pre-flight blocks on an axis, naming each one; force launches anyway.

GET

/campaigns/{campaign_id}/retrigger/check

Whether this campaign can be re-run, reported per axis (config version, container protocol, images, plugins, asset providers). Changes nothing and starts no container, so it is the cheap thing to call before a retrigger.

POST

/campaigns/{campaign_id}/retrigger/workspace

Materialise this campaign as a workspace with its config migrated as far as it could be and a marker at every decision left. Nothing is launched. For a config no migration step can carry forward.

POST

/campaigns/{campaign_id}/scheduling

Set how the queue treats a campaign: its rank, whether it admits new runs, or both. Ordering only — nothing already running stops.

GET

/campaigns/{campaign_id}/search/history

Return a search’s per-batch objective trajectory.

GET

/campaigns/{campaign_id}/status

Return the campaign’s live Status (phase, progress, history).

POST

/campaigns/{campaign_id}/stop

Request a cooperative stop of a running campaign.

image-builds

Method

Path

Description

POST

/image-builds

Build the derived images the project’s containers declare.

GET

/image-builds/{build_id}/log

Return the builder’s raw log from byte offset onward.

GET

/image-builds/{build_id}/status

Return an image build’s live status (phase, done, structured error).

exec

Method

Path

Description

DELETE

/exec

Stop the held exec container, if there is one.

POST

/exec

Run one command in the experiment image and return what it produced.

POST

/exec/resolve-image

Resolve the image exec_in_container() would use for request, without

results

Method

Path

Description

POST

/campaigns/archives

Grant a one-time PUT for a campaign archive.

PUT

/campaigns/archives/{token}

Redeem a one-time token and stream a campaign archive to disk.

POST

/campaigns/import

Take a campaign in – from a staged upload, a host path, or the share.

GET

/campaigns/{campaign_id}/contribution

What one configuration of a campaign contributes to its view: the markers its

GET

/campaigns/{campaign_id}/describe

Describe a campaign’s tables in the index (+ the campaign schema).

GET

/campaigns/{campaign_id}/notebook

Execute workload’s level notebook for the selected node and return the

GET

/campaigns/{campaign_id}/panels

Return the campaign’s run-view panels (top-level visualization.panels

GET

/campaigns/{campaign_id}/panels/source

Return the effective visualization: block as editable YAML text

POST

/campaigns/{campaign_id}/panels/source

Persist an edited visualization: block as a new .vast override

GET

/campaigns/{campaign_id}/plots

Return the campaign’s user-declared plots (evaluation.plots in its

GET

/campaigns/{campaign_id}/postprocessing

Return the campaign’s effective postprocessing entries + revisions.

POST

/campaigns/{campaign_id}/postprocessing

Write a new versioned postprocessing override (validated).

POST

/campaigns/{campaign_id}/postprocessing/run

(Re)run analysis postprocessing for one campaign with the effective config.

GET

/campaigns/{campaign_id}/postprocessing/source

Return the effective results_processing.postprocessing block as

POST

/campaigns/{campaign_id}/postprocessing/source

Persist an edited postprocessing block as a new .vast override

POST

/campaigns/{campaign_id}/query

Run a read-only SELECT, scoped to campaign_id.

GET

/campaigns/{campaign_id}/query.csv

Stream the same read-only SELECT as CSV, with no row cap.

GET

/campaigns/{campaign_id}/scene

Is this run’s 3D geometry ready, and if not what is happening about it.

POST

/campaigns/{campaign_id}/scene/run

Build this run’s geometry unless it is cached, and return at once.

GET

/campaigns/{campaign_id}/scene_assets/{path:path}

Serve one file of a cached scene descriptor (<key>/scene.json, <key>/tex_0.png, …).

POST

/campaigns/{campaign_id}/screenshot

Re-render one moment of a run from a viewpoint you choose, as a PNG.

GET

/campaigns/{campaign_id}/screenshots/{name}

A render POST .../screenshot kept, fetched again by the name it was kept under.

POST

/campaigns/{campaign_id}/share/run

(Re)trigger the upload-to-share of one finished campaign’s raw archive.

GET

/campaigns/{campaign_id}/track_deviation

How far one recorded track (frame of run run_id, from pose table source)

GET

/campaigns/{campaign_id}/visualizations

Return the campaign’s evaluation.visualization notebook workloads

GET

/share/archives

What the configured share holds, read with this service’s own credentials.

admin

Method

Path

Description

DELETE

/admin/cache

Remove every cache entry nothing may still be using, and say what that freed.

GET

/admin/cache

What the service’s rebuildable caches hold, and what a clear would keep and why.

GET

/admin/config

What this service is configured with, read back out of its own environment.

GET

/admin/events

What this service did, from cursor since – durable across restarts.

GET

/admin/log

This service’s own recent log, from byte offset – what it has been doing.

GET

/admin/log/stream

SSE: this service’s own log, tailed live (Last-Event-ID resumes).

GET

/admin/mcp-calls

The MCP call log, newest first – what each call was given and what it answered.

GET

/admin/mcp-calls.csv

The same log as a CSV download – the repo’s one export format.

GET

/admin/mcp-tools

Which MCP tools get called, how often, and how many of those calls failed.

GET

/admin/upgrade

What version is running, whether something newer is published, and may we roll.

POST

/admin/upgrade

Roll this service onto the newest image at its resolved tag.

plugin-endpoints

Method

Path

Description

GET

/campaigns/{campaign_id}/costmap

Run data from the ‘costmap’ endpoint plugin.