API reference

Every route under /api. Generated by hand from the handlers and kept honest by tests/consistency.test.ts, which fails the build if a route exists and this file does not mention it.

Authentication

One funnel for every caller. A route either takes an authenticated tenant or refuses — there is no separate “browser API”.

Authorization: Bearer <api-key>      # machines. Settings → API keys
Cookie: foldrun_session=...          # the dashboard, same-origin

It fails closed. It used to be the other way round — no key meant “trust the x-foldrun-tenant header” unless a flag was set — which let anyone who reached the deployment read every workspace and write any secret. A missing flag should refuse, not admit.

FOLDRUN_DEV_NO_AUTH=1 opts out for local development only, and only next dev sets it.

Errors are { "error": "..." } with a real status: 401 unauthenticated, 402 out of credit, 404 missing, 409 conflict, 422 a refusal you have to read (a deploy with issues), 429 rate limited.

Quick start

export FOLDRUN_TOKEN=...  FOLDRUN_URL=https://your-server  WS=my-workspace
api() { p=$1; shift; curl -sS -H "authorization: Bearer $FOLDRUN_TOKEN" \
        "$FOLDRUN_URL/api/$p" "$@"; }

api workspaces/$WS/runs                        # what has run
api workspaces/$WS/runs/<id>                   # every step of one
api workspaces/$WS/flows/publish/run -X POST   # start a flow

Workspaces

Source — the files themselves

Editing one file at a time. For a whole tree, deploy.

Deploy

POST /api/workspaces/<ws>/deploy

{ "files": [{ "path": "agents/x/agent.md", "content": "..." }],
  "commit": "abc123", "force": false, "dryRun": false }

Returns { ok, applied, added, changed, removed, issues }. 422 with ok:false is a refusal, not a transport failure — read issues. A workspace is declarative, so the whole of it is checked before any of it goes live: a broken flow is caught at push time rather than at 3am when its schedule fires.

dryRun: true checks and changes nothing. force: true deploys over a live run, which otherwise refuses — swapping files under a running flow means step 3 reads agents step 1 never saw.

Never touched by a deploy: runs/, state/, secrets.json, and any memory an agent wrote that the push does not mention.

Flows

POST .../run takes task (the input), from (start at step N — a rerun of the interesting half), and tags. Returns { ok, runId, steps, from }.

Agents and evals

Running an agent alone is the fastest way to test a prompt change without paying for the steps around it.

Runs — the debug loop

status is one of queued, running, awaiting-approval, completed, failed.

summary is what the run concluded, in one line: the first line of the last step that produced a result, captured when the run finishes. Nothing declares it and nothing has to — agents are asked to lead with a headline, and this reads the line they already wrote. It is what the runs list shows under a row and what a notification puts in its subject, so a run answers “what did this do” without being opened. Null on a run that produced no output at all.

approve takes decision (approve or reject), step, and a note or reason — the note is kept on the run, so why a human said yes survives.

A run that parks on a human also emails or POSTs its notification with approveUrl and rejectUrl (see /api/approve/… under Triggers) when FOLDRUN_PUBLIC_URL names the install’s public origin; without it the notification goes out without links and the worker logs why, once. The step’s trace says which door the decision came through: “approved by a human” from the dashboard, “approved via emailed link” from the link, “approved by an external event” when a wait: event step was released.

A step that declared output: json carries its parsed value as data beside result; a wait: event step carries what released it as eventPayload; and a run of a flow with budget: carries the cap it was held to as budgetUsd, stamped when it started. memoryWrites lists the memory files the run created or changed, workspace-relative, so what the agents decided to remember can be reviewed without diffing the folder.

A run that worked is worth keeping: promote writes its task and its conclusion into evals/ as a case, appending when the file exists. A flow’s file is born trigger: manual — each case costs a whole run — so it runs when a person presses Run, not on every push.

The usual loop: runs to find it → runs/<id> to see which step failed and what it cost → fix the markdown → deploy → rerun.

Storage — workspace files agents produce

Blobs go to object storage; the index of what exists stays local. Presigned URLs mean nothing in a run pod ever holds the bucket credential.

Shares — a public link to one file

POST returns a url under /s/<token>. That URL is the only route on the server that answers without a credential — the token is the authorisation, so it carries 24 random bytes and is never derived from the path.

Only storage/, files/ and outputs/ can be shared. An agent talked into sharing something is confined to what the workspace produced and can never hand out memory/, an agent’s prompt, or a credential.

Links expire in 7 days unless ttlDays says otherwise (null never expires). Revoking is permanent; a re-share mints a new token rather than reviving an old one. Every failed fetch is the same 404, so a guesser learns nothing about whether a token was ever real.

This needs FOLDRUN_PUBLIC_URL — the origin the outside world reaches this install on. Without it POST returns 409 rather than handing back a link that only works from inside.

It exists because some work is not done until something outside can fetch the bytes: a Google Business Profile post will not accept uploaded image data for its header and requires a URL it can GET for itself.

Secrets

GET, PUT, DELETE /api/secrets

PUT takes name plus exactly one shape: value (a string), file (a PEM, a cert), oauth2, service_account, ssh, or api. They go to the vault; agents name them in secrets: and never see them in a file.

Reads return which secrets exist, never their values.

Account

Roles

Every member and every API key has a role, and every write route asks for the least role that may take that action. Reads are open to every role.

There is exactly one owner: the account’s creator until they transfer it. The owner is never re-roled or removed — transfer first. Nobody changes their own role. An admin cannot promote to admin or remove one; that is the owner’s, because an admin who can promote peers is an owner with extra steps.

A refused call answers 403 with the role that was needed. A key is minted with a role (editor unless you say otherwise) and keys from before roles existed act as admin — the power they always had. Acts against a named member — inviting, re-roling, removing, transferring — need a signed-in person: a key names an account, never a who.

Billing

Authentication routes

Login is rate limited per IP, which only works when FOLDRUN_TRUST_PROXY=1 tells the platform a real proxy is reporting the caller.

Signing the CLI in

foldrun login is the device-authorization shape: the terminal holds a secret request id, the person sees only a short code, and approval — by a signed-in person, never by a key — mints an ordinary API key at their role.

OAuth — connecting an agent to a third party

Triggers

Operations

healthz reports a failing database rather than refusing, because taking the web tier out of the load balancer for a dependency it can still serve most pages without is the wrong trade.