foldrun 26.3.3 → 26.3.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/foldrun.mjs +60 -60
- package/docs/a2a.md +12 -12
- package/docs/agents.md +21 -21
- package/docs/api-usage.md +2 -2
- package/docs/api.md +98 -98
- package/docs/assistant.md +21 -21
- package/docs/backups-and-restore.md +11 -11
- package/docs/budgets-and-billing.md +21 -21
- package/docs/checks.md +19 -19
- package/docs/cli.md +100 -100
- package/docs/coding-agents.md +8 -8
- package/docs/deploying.md +7 -7
- package/docs/evals.md +6 -6
- package/docs/extract.md +1 -1
- package/docs/faq.md +5 -5
- package/docs/feature-flags.md +1 -1
- package/docs/flows.md +14 -14
- package/docs/four-jobs.md +5 -5
- package/docs/getting-started.md +10 -10
- package/docs/glossary.md +9 -9
- package/docs/hooks.md +5 -5
- package/docs/how-it-works.md +1 -1
- package/docs/introduction.md +4 -4
- package/docs/knowledge-and-memory.md +6 -6
- package/docs/mcp.md +15 -15
- package/docs/network.md +9 -9
- package/docs/notifications.md +16 -16
- package/docs/oauth.md +1 -1
- package/docs/providers.md +6 -6
- package/docs/runs.md +28 -28
- package/docs/scheduling.md +1 -1
- package/docs/secrets.md +22 -22
- package/docs/security.md +15 -15
- package/docs/self-hosting.md +18 -18
- package/docs/status.md +1 -1
- package/docs/storage-and-sharing.md +14 -14
- package/docs/team-and-access.md +29 -29
- package/docs/tools.md +20 -20
- package/docs/troubleshooting.md +4 -4
- package/docs/workspaces.md +43 -43
- package/package.json +2 -2
- package/src/commands.mjs +131 -131
- package/src/guide.mjs +1 -1
package/docs/api.md
CHANGED
|
@@ -27,7 +27,7 @@ Cookie: foldrun_session=... # the dashboard, same-origin
|
|
|
27
27
|
|
|
28
28
|
It **fails closed**. It used to be the other way round — no key meant "trust
|
|
29
29
|
the `x-foldrun-tenant` header" unless a flag was set — which let anyone who
|
|
30
|
-
reached the deployment read every
|
|
30
|
+
reached the deployment read every project and write any secret. A missing
|
|
31
31
|
flag should refuse, not admit.
|
|
32
32
|
|
|
33
33
|
`FOLDRUN_DEV_NO_AUTH=1` opts out for local development only, and only `next dev`
|
|
@@ -38,24 +38,24 @@ Errors are `{ "error": "..." }` with a real status: `401` unauthenticated,
|
|
|
38
38
|
read (a deploy with issues, an `Idempotency-Key` reused with a different body),
|
|
39
39
|
`429` rate limited (`Retry-After`, `{ error, retry_after }`).
|
|
40
40
|
|
|
41
|
-
**A person's alone.** A key carries a role and a
|
|
41
|
+
**A person's alone.** A key carries a role and a project scope no wider
|
|
42
42
|
than the person who minted it, and opens every route below with that — except
|
|
43
43
|
the ones that are about people: `/api/team` (invite, roles, scope, remove,
|
|
44
44
|
transfer — listing and revoking invites, `/api/team/invites`, take an admin
|
|
45
45
|
key), `/api/auth/*` (profile, password, MFA, sessions), a user's
|
|
46
46
|
`/api/avatars/user/<id>`. Those need a signed-in
|
|
47
47
|
session and answer a key with `401` (a user's avatar answers a key with
|
|
48
|
-
`403`: the key is read, then refused because it is not that person). Everything a
|
|
48
|
+
`403`: the key is read, then refused because it is not that person). Everything a project or an account
|
|
49
49
|
*does* — files, runs, secrets, shares, schedules, hooks, storage, billing —
|
|
50
50
|
takes the key.
|
|
51
51
|
|
|
52
52
|
One key is a person: the one their own `foldrun login` minted (`origin:
|
|
53
53
|
cli-login`). It may also invite (`POST /api/team`), change a member's role or
|
|
54
|
-
|
|
54
|
+
projects and remove them (`PATCH`/`DELETE /api/team/members/<id>`), and set
|
|
55
55
|
that person's name and timezone (`POST /api/auth/name`, `/api/auth/timezone`).
|
|
56
56
|
It acts at the lower of its role and the person's role now — an owner's is an
|
|
57
57
|
admin, so making, changing or removing an admin stays in the browser — in the
|
|
58
|
-
|
|
58
|
+
projects both allow, and the audit entry says `via: foldrun login` with the
|
|
59
59
|
key's id. A request carrying a key is decided by the key, never by a cookie
|
|
60
60
|
beside it. Transfer, password, email, two-step sign-in, sessions, avatars and
|
|
61
61
|
closing the account stay a signed-in session's.
|
|
@@ -74,25 +74,25 @@ api workspaces/$WS/flows/publish/run -X POST # start a flow
|
|
|
74
74
|
|
|
75
75
|
---
|
|
76
76
|
|
|
77
|
-
##
|
|
77
|
+
## Projects
|
|
78
78
|
|
|
79
79
|
| Route | Methods | |
|
|
80
80
|
|---|---|---|
|
|
81
|
-
| `/api/workspaces` | GET, POST | list; create (`name`, plus one of: `template: true` — blank, just an AGENTS.md, what the dashboard sends; `starter: true` — the example researcher, writer and publish flow; `demo: true`; `files`). A POST to a name that exists deploys over it, through the deploy's gate — files that do not check out, or a run still reading the
|
|
82
|
-
| `/api/workspaces/<ws>` | GET, PATCH, DELETE | read; rename or re-describe (`name`, `description` — written as one YAML value and recorded in History), or set its defaults (`timezone`, `budget`, `compute` — `{ vcpu, memGiB, diskGiB }`, this
|
|
83
|
-
| `/api/workspaces/<ws>/pause` | GET, POST, DELETE | the
|
|
84
|
-
| `/api/workspaces/<ws>/vocabulary` | GET | which document kinds this
|
|
85
|
-
| `/api/workspaces/<ws>/check` | GET | what `foldrun check` says about the deployed copy, as findings with rule ids — what a deploy refuses or warns about, and the scanner's secret, hidden-text, agent-risk and supply-chain rules ([Checks](checks)). `?security=1` keeps the security rules, `?rule=<id or category>` (repeatable) one, `?online=1` adds the network checks (known vulnerabilities, remote MCP tool text) — editor and above, since they send the server out to OSV and the
|
|
81
|
+
| `/api/workspaces` | GET, POST | list; create (`name`, plus one of: `template: true` — blank, just an AGENTS.md, what the dashboard sends; `starter: true` — the example researcher, writer and publish flow; `demo: true`; `files`). A POST to a name that exists deploys over it, through the deploy's gate — files that do not check out, or a run still reading the project, are `422` with `issues`/`blockedBy` and nothing changes, and it is audited as `workspace.deployed`; add `ifAbsent: true` to create only — a name that exists is then `409` and nothing changes, decided atomically (the assistant's Create project and `foldrun assistant` send it) |
|
|
82
|
+
| `/api/workspaces/<ws>` | GET, PATCH, DELETE | read; rename or re-describe (`name`, `description` — written as one YAML value and recorded in History), or set its defaults (`timezone`, `budget`, `compute` — `{ vcpu, memGiB, diskGiB }`, this project's own pool, merged over what is set —, `notify`, `network_enforce`, `owner`, `alerts`, `judge` — null clears one, edited in AGENTS.md in place; keys only the account may set are ignored); delete — its stored files and public links go with it, as a rename moves them. An account secret limited to it ([limited to some projects](secrets#limited-to-some-projects)) follows a rename and loses it on a delete, done before the folder moves or goes: 409 naming any such secret the platform's keys cannot read (nothing renamed or deleted), 503 when the vault cannot be updated; a rename onto a name that exists is 409 |
|
|
83
|
+
| `/api/workspaces/<ws>/pause` | GET, POST, DELETE | the project's kill switch. GET `{ paused, account, workspace }` — what holds runs here (`paused` is the one that applies, `scope` saying whose), each `{ at, by, reason? }` or null. POST `{ reason?, stop?: true }` pauses: every start here — schedule, webhook, chained flow, a person's Run, a rerun — is refused `423` with who paused it, and a refused trigger is logged as `halted`; A run queued before the pause and not yet begun waits until the resume. `stop: true` also stops every running, queued and parked run (needs `run:start`) and answers `stopped` and `failed`. DELETE resumes. Needs `workspace:manage`. The account's pause holds here too and only the account's DELETE lifts it; an operator's suspension is separate and neither lifts it |
|
|
84
|
+
| `/api/workspaces/<ws>/vocabulary` | GET | which document kinds this project admits — its `docs` list is what `[[ ]]` resolves: knowledge, memory, `state/` and `storage/` files, plus the folders themselves. `secrets` names the project's secrets and, to a caller with every project, the account's (as `GET /api/secrets` lists them). `404` when the project does not exist |
|
|
85
|
+
| `/api/workspaces/<ws>/check` | GET | what `foldrun check` says about the deployed copy, as findings with rule ids — what a deploy refuses or warns about, and the scanner's secret, hidden-text, agent-risk and supply-chain rules ([Checks](checks)). `?security=1` keeps the security rules, `?rule=<id or category>` (repeatable) one, `?online=1` adds the network checks (known vulnerabilities, remote MCP tool text) — editor and above, since they send the server out to OSV and the project's MCP servers; the answer is kept for 10 minutes while the files are unchanged, and a project gets six fresh online passes per 10 minutes (then `429` with `Retry-After`); `{ counts, findings: [{ rule, level, file, line, message, fingerprint }], rules, online?: { problems, sources }, rescan: { checkedAt, findings, pending, problems } | null }`. Read-only, no model call |
|
|
86
86
|
|
|
87
87
|
## Source — the files themselves
|
|
88
88
|
|
|
89
89
|
| Route | Methods | |
|
|
90
90
|
|---|---|---|
|
|
91
|
-
| `/api/workspaces/<ws>/source?path=` | GET, PUT, PATCH, DELETE | GET: one file (`{ path, content, sha256 }`), or the tree with no `path`. PUT `{path, content, message?, ifMatch?, check?}` writes one file (a revision, `message` its note) and answers `{ ok, path, sha256, issues }`, the deploy's checks for that file as saved. With `check: true` (what the dashboard editor sends) a file with an error a deploy would refuse is refused with `422` and the `issues`, nothing written; warnings never refuse; with `ifMatch` — the `sha256` a GET returned — it is refused with `409` and nothing written if the file has changed since; `ifMatch: null` says the caller saw no file there, and is refused the same way once one exists (History's restore and the AI draft's save send it, the draft's new files as `null`). PATCH `{from, to}` moves one. DELETE `{path}` removes a file or folder. A write names a
|
|
91
|
+
| `/api/workspaces/<ws>/source?path=` | GET, PUT, PATCH, DELETE | GET: one file (`{ path, content, sha256 }`), or the tree with no `path`. PUT `{path, content, message?, ifMatch?, check?}` writes one file (a revision, `message` its note) and answers `{ ok, path, sha256, issues }`, the deploy's checks for that file as saved. With `check: true` (what the dashboard editor sends) a file with an error a deploy would refuse is refused with `422` and the `issues`, nothing written; warnings never refuse; with `ifMatch` — the `sha256` a GET returned — it is refused with `409` and nothing written if the file has changed since; `ifMatch: null` says the caller saw no file there, and is refused the same way once one exists (History's restore and the AI draft's save send it, the draft's new files as `null`). PATCH `{from, to}` moves one. DELETE `{path}` removes a file or folder. A write names a project that exists — to one that does not it is `404`, and nothing is made (make it with `POST /api/workspaces`, a deploy or an import); the same holds for every route that writes a file: agents, evals, flows, assets, settings. The body carries the path on writes — a `?path=` there is a `400`. A change to a policy key of the project's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-projects-policy-is-an-admins)) |
|
|
92
92
|
| | PUT | write (`path`, `content`, optional `message` — recorded on the revision, as `foldrun source put --message` sends it) |
|
|
93
93
|
| | PATCH | move (`from`, `to`) |
|
|
94
94
|
| | DELETE | remove (`path`) |
|
|
95
|
-
| `/api/workspaces/<ws>/source/share` | POST | **Move to shared**: a skill, tool, script, knowledge or memory file into the account library and out of the
|
|
95
|
+
| `/api/workspaces/<ws>/source/share` | POST | **Move to shared**: a skill, tool, script, knowledge or memory file into the account library and out of the project, in one call — `path` (`skills/x/SKILL.md`, `tools/x/tool.md` or the folder moves the whole folder), `overwrite` (replace library files already there; `409` otherwise), `dryRun` (what would move, nothing written). Everything is checked first: a folder holding a file the library cannot hold (an image, a binary), one too large or with broken frontmatter is refused `409` and nothing changes. `{ ok, kind, unit, files: [{ from, to, replaces }], moved }`. Account-wide callers only (`workspace:write`), as for the library itself. Hooks are refused. Idempotent |
|
|
96
96
|
|
|
97
97
|
Editing one file at a time. For a whole tree, deploy. The files this door
|
|
98
98
|
writes are text: markdown, and a script's or a register's own formats —
|
|
@@ -110,14 +110,14 @@ writes are text: markdown, and a script's or a register's own formats —
|
|
|
110
110
|
```
|
|
111
111
|
|
|
112
112
|
Returns `{ ok, applied, commit, added, updated, removed, preserved }`; with `dryRun: true`, `{ ok, applied: false, added, updated, removed, issues, blockedBy }` and nothing is written. Over 10 MB is `413`. **`422` with
|
|
113
|
-
`ok:false` is a refusal, not a transport failure** — read `issues`. A
|
|
113
|
+
`ok:false` is a refusal, not a transport failure** — read `issues`. A project
|
|
114
114
|
is declarative, so the whole of it is checked before any of it goes live: a
|
|
115
115
|
broken flow is caught at push time rather than at 3am when its schedule fires.
|
|
116
116
|
|
|
117
|
-
A deploy to a name with no
|
|
117
|
+
A deploy to a name with no project yet makes one, so it needs what making
|
|
118
118
|
one needs anywhere: the `admin` role (`workspace:manage`), and on a hosted
|
|
119
|
-
plan room under its
|
|
120
|
-
/api/workspaces` and an import of a
|
|
119
|
+
plan room under its project count (`402` otherwise) — as `POST
|
|
120
|
+
/api/workspaces` and an import of a project package. A deploy to a project
|
|
121
121
|
that exists needs `editor`. `commit` is a commit id (letters, digits, `.`, `_`,
|
|
122
122
|
`@`, `-`, at most 121 characters), `400` before anything is written otherwise;
|
|
123
123
|
it names the deploy's revision the first time it is deployed, and a later
|
|
@@ -140,11 +140,11 @@ agent wrote that the push does not mention.
|
|
|
140
140
|
|
|
141
141
|
| Route | Methods | |
|
|
142
142
|
|---|---|---|
|
|
143
|
-
| `/api/workspaces/<ws>/deploy` | POST | deploy the whole
|
|
144
|
-
| `/api/workspaces/<ws>/runtimes` | GET | the `runtime:` builds a deploy started, each with its `state` — below. `404` when the
|
|
143
|
+
| `/api/workspaces/<ws>/deploy` | POST | deploy the whole project from a list of files — checked as a whole first, refused with `422` and `issues` when it does not check out. `dryRun`, `force`, `expectRemoved` below. A change to a policy key of the project's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-projects-policy-is-an-admins)); a dry run is not refused, and answers `policy: { status, code, error }` when the real deploy would be. Behind a flow published over A2A, an editor's deploy that widens an agent is `403` `code: a2a_widening`, and anyone's that makes a secret-and-code agent with no `a2a: accept_risk` is `400` `code: a2a_secret_code` — on every write door: this, `PUT`/`PATCH`/`DELETE /source`, import, restore, a proposed fix ([A2A](a2a.md#an-editor-cannot-widen-a-published-flow)). Idempotent |
|
|
144
|
+
| `/api/workspaces/<ws>/runtimes` | GET | the `runtime:` builds a deploy started, each with its `state` — below. `404` when the project does not exist |
|
|
145
145
|
|
|
146
146
|
`GET /api/workspaces/<ws>/runtimes` answers what a deploy started on the
|
|
147
|
-
platform: every distinct `runtime:` the
|
|
147
|
+
platform: every distinct `runtime:` the project's agents need
|
|
148
148
|
(`fingerprint`, `agents`, `python`, `packages`, `npm`, `system` — the Debian
|
|
149
149
|
packages it apt-installs — and `rejected` for entries that are not
|
|
150
150
|
requirements), each with the `state` of the build the
|
|
@@ -156,7 +156,7 @@ installer's `error`, its cause on the first line. `foldrun deploy` polls it afte
|
|
|
156
156
|
| Route | Methods | |
|
|
157
157
|
|---|---|---|
|
|
158
158
|
| `/api/workspaces/<ws>/flows` | GET, POST | list; create (`name`, `pattern`) |
|
|
159
|
-
| `/api/workspaces/<ws>/a2a` | GET | what this
|
|
159
|
+
| `/api/workspaces/<ws>/a2a` | GET | what this project serves to outside agents over A2A 1.0: `{ flows: [{ flow, published, publicCard, name, description, hasInputSchema, acceptRisk, card, url }], risks: [{ flow, agent, secrets, accepted }], keys, tasks: [{ id, flow, state, runId, contextId, key: { id, label, prefix, revoked }, createdAt, updatedAt }] }` — every flow whose frontmatter says `a2a:`; `risks`, every flow's agents (published or not) that hold a secret and can run code, with whether its `a2a: accept_risk` names them — a published flow with one not accepted takes no new task ([accept_risk](a2a.md#secret-and-code-accept_risk)); the URL of its agent card and of its JSON-RPC endpoint (`/a2a/<account>/<ws>/flows/<flow>`), the project's live A2A keys (`[{ id, label, prefix, flows, maxTasks, expiresAt }]`, or `null` unless you may manage keys), and the 50 newest A2A tasks (`state` a `TASK_STATE_*`) with the key that asked. Publishing is the flow's `a2a:` field, written like any other — changing it needs `workspace:manage`. `404` when the project does not exist |
|
|
160
160
|
| `/api/workspaces/<ws>/flows/<flow>` | PATCH | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), set `a2a` (`{ publish, name, description, examples, public_card, input, accept_risk }` merged over the flow's `a2a:` — a key sent replaces it, `null` removes it; `a2a: null` removes the block; refused `400` when the result would not read, `403` without the admin role, `400` `code: a2a_secret_code` when an agent of the published flow holds a secret and can run code and `accept_risk` does not name it — see [A2A](a2a.md)), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that; adding a step is `edit: { op: "insert", target, subflow?, instruction?, at: { rail } }`, removing one `edit: { op: "remove", step }`), undo (`restore` + `expect`). The older POST (a step at the end) and DELETE (`{ step }`) were removed on 5 Nov 2026 (deprecated and sunset the same day) — every client (the canvas, the list view's board, the CLI) sends PATCH `{ edit }`, one mechanism per change; `DELETE …/flows/draft` answers `410`. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
|
|
161
161
|
| `/api/workspaces/<ws>/flows/draft` | POST, PATCH, DELETE | POST draft a flow with a model: `{ description, flow? }` (`flow` redrafts that one). Returns `{ ok, files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], repaired, notes }` — checked with the deploy's checks and the flow lint, repaired once. **Writes nothing**; save with the source PUT. Needs `workspace:write`; a description over 4,000 characters is `413`; a Chat-Completions `provider:` is `422`. On the platform's models the balance is checked first (`402`) and the call is charged as one ledger line, flow `ai-draft`. PATCH and DELETE, and a POST without `description`, are the edits of a flow that happens to be named `draft`, exactly as at `flows/<flow>` |
|
|
162
162
|
| `/api/workspaces/<ws>/flows/<flow>/run` | POST | start it. `customer` names which of your own users it is for ([end customers](runs#end-customers)). `inputs` (storage paths) hands files to the first step at `inputs/` ([inputs](runs#inputs)); not with `from`. `context` (1–200 printable ASCII characters) makes the run a turn of that [conversation](runs#conversations): its first step reads the earlier runs of the same context before the task; not with `from` (`400`); the answer carries `context`. An `Idempotency-Key` header, or `idempotencyKey` in the body, makes a retried call safe: a dropped response, a proxy timeout or a CI step that ran twice is answered `started: false` with the `runId` it already started, rather than starting a second run and billing for it. Keys are remembered for 24 hours, per flow. While the account has its most runs waiting for their turn it answers 409 `{ error, code: "waiting_cap", limit, waiting }` and starts nothing ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); so do the agent run and rerun routes (an A2A caller is told the agent is busy), and a webhook or inbound email gets the same as a 503 with `Retry-After: 60` |
|
|
@@ -174,14 +174,14 @@ Left out, a run is live.
|
|
|
174
174
|
|
|
175
175
|
| Route | Methods | |
|
|
176
176
|
|---|---|---|
|
|
177
|
-
| `/api/workspaces/<ws>/assistant` | POST | one reply from the assistant, which answers from the foldrun docs and this
|
|
178
|
-
| `/api/assistant/conversations?workspace=&q=&limit=` | GET | the asker's kept assistant conversations — a person's own, or a key's own — newest first, across the
|
|
179
|
-
| `/api/assistant/conversations/<id>` | GET, DELETE | one kept conversation, whole: `{ id, workspace, title, messages: [{ role, content, meta? }], files, createdAt, updatedAt }` (`meta` is what the dashboard draws under a reply: sources, tokens, charge, a proposed
|
|
177
|
+
| `/api/workspaces/<ws>/assistant` | POST | one reply from the assistant, which answers from the foldrun docs and this project's files only and writes agents, flows, tools and skills: `{ messages: [{ role: "user"\|"assistant", content }], files?: [{ path, content }], page?, conversation? }` — the conversation so far (the last message the person's, at most 8,000 characters), the files it proposed that are not saved yet, and the dashboard page being looked at. Returns `{ ok, reply, files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], sources: [{ doc, section, url }], supply, workspace, usage, chargedUsd }` — `files` is every unsaved proposal as it now stands, checked; `workspace` is `{ name, purpose }` when it proposes a new project (free and kebab-case when proposed; create it with `POST /api/workspaces { name, template: true }`, then talk to the assistant there), else `null`; `usage` is `{ inputTokens, outputTokens, costUsd }` across every model call of the reply; `chargedUsd` what the account was charged for it on the platform's models (the same price as a run's tokens), `null` on its own provider; `conversation` is the id it was kept under — send it back as `conversation` to carry on (without one, a new conversation starts). **Writes nothing**; save with the source PUT (`ifMatch` the `sha256`, `null` for a new file). With `Accept: text/event-stream` it streams `status` (what it is reading), `text` (the reply as it is written), then `done` with the same body, or `error`. Needs `workspace:write`; 60 replies an hour per person or key, and on the platform's models 300 a day per account (`429`); at most 200 messages of 60,000 characters each (`413`). Closing the stream does not stop the reply: it finishes (at most $2, 30 tool calls, five minutes) and is charged; a Chat-Completions `provider:` is `422`. On the platform's models the balance is checked first (`402`) and each reply is one ledger line, flow `ai-assistant` |
|
|
178
|
+
| `/api/assistant/conversations?workspace=&q=&limit=` | GET | the asker's kept assistant conversations — a person's own, or a key's own — newest first, across the projects they may see: `{ conversations: [{ id, workspace, title, updatedAt, messages, unsaved }] }`. `q` searches the titles and every message; `workspace` narrows to one; `limit` 1–200 (50) |
|
|
179
|
+
| `/api/assistant/conversations/<id>` | GET, DELETE | one kept conversation, whole: `{ id, workspace, title, messages: [{ role, content, meta? }], files, createdAt, updatedAt }` (`meta` is what the dashboard draws under a reply: sources, tokens, charge, a proposed project); DELETE removes it. Anyone else's id is `404`, the same as none |
|
|
180
180
|
|
|
181
181
|
It may propose only `flows/<name>.md`, `agents/<name>/agent.md`,
|
|
182
182
|
`skills/<name>/SKILL.md` (and files under the skill's `scripts/`,
|
|
183
183
|
`references/` or `assets/`), and `tools/<name>/tool.md` with its program, or
|
|
184
|
-
`tools/<name>.md`. It reads the
|
|
184
|
+
`tools/<name>.md`. It reads the project's source and the account library,
|
|
185
185
|
never `state/`, `storage/`, runs or secrets. A proposal is checked with the
|
|
186
186
|
deploy's checks and the flow lint; a frontmatter key the docs never name, and
|
|
187
187
|
a value shaped like a credential, are errors.
|
|
@@ -197,24 +197,24 @@ history with each message.
|
|
|
197
197
|
|
|
198
198
|
| Route | Methods | |
|
|
199
199
|
|---|---|---|
|
|
200
|
-
| `/api/workspaces/<ws>/agents` | GET, POST | list — each agent's frontmatter as read, `owner` and `ownerFrom` (its own `owner:`, else the
|
|
200
|
+
| `/api/workspaces/<ws>/agents` | GET, POST | list — each agent's frontmatter as read, `owner` and `ownerFrom` (its own `owner:`, else the project's, else the account's), `lastRunAt` (when its latest step that ran started, from the runs kept; null for none) and `stale` (past `alerts: stale_days`); create (`name`) |
|
|
201
201
|
| `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description" | "sandbox", value } }` (`sandbox` takes `own` or `parent`, else 400), or `{ network }` — the sites its sandbox may reach: `"open"`, `"trusted"`, `"none"`, a list of sites, or `{ level, allow, defaults }`; `null` removes the line so it inherits ([Network](network)). A `network` nobody could read is a 400 that says why. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
|
|
202
|
-
| `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run; `customer`: which of your own users it is for ([end customers](runs#end-customers): its limits and blocks follow it; `403` code `customer_blocked`, `429` code `customer_rate` with `Retry-After`, or `customer_open_runs`); `inputs`: storage paths handed to the step at `inputs/` ([inputs](runs#inputs): at most 20 and 100 MiB, held as they are when the run is made; `404` names a path with no stored file, `409` where the install has no sandbox to stage them; the answer lists them); `context`: a [conversation](runs#conversations) the run is a turn of — the agent reads the earlier runs of the same context before the task, and the answer carries `context`; `snapshot`: a folder to work on, the id `POST …/snapshots` answered — the step finds it in `snapshot/`, only its `outputs/` come back to the
|
|
203
|
-
| `/api/workspaces/<ws>/agents/import` | GET, POST | copy an agent in from another
|
|
204
|
-
| `/api/workspaces/<ws>/proposals` | GET | the
|
|
202
|
+
| `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run; `customer`: which of your own users it is for ([end customers](runs#end-customers): its limits and blocks follow it; `403` code `customer_blocked`, `429` code `customer_rate` with `Retry-After`, or `customer_open_runs`); `inputs`: storage paths handed to the step at `inputs/` ([inputs](runs#inputs): at most 20 and 100 MiB, held as they are when the run is made; `404` names a path with no stored file, `409` where the install has no sandbox to stage them; the answer lists them); `context`: a [conversation](runs#conversations) the run is a turn of — the agent reads the earlier runs of the same context before the task, and the answer carries `context`; `snapshot`: a folder to work on, the id `POST …/snapshots` answered — the step finds it in `snapshot/`, only its `outputs/` come back to the project, and the run's outputs hold `snapshot.patch`, the change as a git patch, with `snapshot.json` saying what it touched or why there is none. Needs the k8s sandbox: `409` on an install without it, `404` for a snapshot not in this project) |
|
|
203
|
+
| `/api/workspaces/<ws>/agents/import` | GET, POST | copy an agent in from another project of the account. GET lists what could be imported (every other project you can read, with its agents). POST `{ from, agent, as? }` copies `agents/<agent>/` — its agent.md and own skills/, scripts/, knowledge/; never memory/, outputs/, state/ — and answers `{ name, files, warnings }`; `warnings` names tools, skills, scripts and secrets the copy uses that this project lacks. 409 on a name clash (pass `as`), 404 for an unknown project or agent, 403 when `from` is outside your key's scope. Idempotent |
|
|
204
|
+
| `/api/workspaces/<ws>/proposals` | GET | the project's proposed fixes, newest first (`404` when the project does not exist): `{ proposals: [{ id, workspace, eval, by (auto, or who asked), createdAt, updatedAt, status, failures: [{ runId?, case?, check, detail, at }], jobId, reply (the assistant's reasoning), files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], error?, notes?, decidedBy?, decidedAt?, applied? }] }`. `status` is `drafting`, `ready`, `failed`, `applying`, `applied`, `partial` (a write failed part-way; `applied` names what was written) or `dismissed`. `?status=`, `?eval=`. A drafting one is settled as it is read |
|
|
205
205
|
| `/api/workspaces/<ws>/proposals/<id>` | GET, POST | one proposal. `POST { action: "apply" }` writes its files, each a revision by the caller, only when every one still reads what it was drawn against (`409` naming the file that changed) and can be written (`422`; a check error the deploy would refuse is `422` too); `POST { action: "dismiss" }` sets it aside — its failures stay looked at. Only agents, flows and skills are ever in one. Needs `workspace:write` |
|
|
206
|
-
| `/api/workspaces/<ws>/export` | GET | this
|
|
207
|
-
| `/api/workspaces/<ws>/import` | POST | take a package in; the body is the `.zip` (`content-type: application/zip`, at most 20 MB). `?dryRun=1` answers `{ kind, name, from, creates, added, overwritten, unchanged, needs: { secrets, tools, skills, scripts, agents, flows } }` plus `skipped` (entries it will not write: memory, state, anything outside the authored folders) and writes nothing. Without it, applies as one revision; 409 when it would replace a file with different text unless `?overwrite=1`, or when a file cannot be written there (all or nothing). Never deletes. A `Content-Length` is required (411 without). A
|
|
208
|
-
| `/api/workspaces/<ws>/snapshots` | POST | send a folder for an agent on foldrun to work on (a snapshot). The body is the folder as a `.tar.gz` (`content-type: application/gzip`, at most 50 MB compressed; a `Content-Length` is required, 411 without) — what `foldrun snapshot push` makes. Checked on the server whatever the client did: plain files and folders only (no links, devices or extended headers), no path that leaves the folder or differs from another only by case, at most 20,000 entries, 10 MB a file and 200 MB unpacked, and no secret — `422` naming the file and line, never the value. Answers `{ snapshotId, files, bytes, compressedBytes, expiresAt, reused }`: `201`, or `200` when this
|
|
206
|
+
| `/api/workspaces/<ws>/export` | GET | this project, one flow or one agent as a `.zip` — `?kind=flow&name=<flow>` (the flow, every flow it runs as a step, every agent those steps and their colleagues name, and the project tools, skills and scripts they grant), `?kind=agent&name=<agent>` (its folder and what it grants), or neither for the whole authored tree. Never memory/, state/, outputs/, storage, runs or a secret's value; `foldrun-package.json` inside says what it is. Any role that can read the project |
|
|
207
|
+
| `/api/workspaces/<ws>/import` | POST | take a package in; the body is the `.zip` (`content-type: application/zip`, at most 20 MB). `?dryRun=1` answers `{ kind, name, from, creates, added, overwritten, unchanged, needs: { secrets, tools, skills, scripts, agents, flows } }` plus `skipped` (entries it will not write: memory, state, anything outside the authored folders) and writes nothing. Without it, applies as one revision; 409 when it would replace a file with different text unless `?overwrite=1`, or when a file cannot be written there (all or nothing). Never deletes. A `Content-Length` is required (411 without). A project package into a name that does not exist makes that project (`workspace:manage`, the plan's project count). 400 for anything not a package, or one holding memory/, state/ or outputs/. A change to a policy key of the project's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-projects-policy-is-an-admins)). Idempotent |
|
|
208
|
+
| `/api/workspaces/<ws>/snapshots` | POST | send a folder for an agent on foldrun to work on (a snapshot). The body is the folder as a `.tar.gz` (`content-type: application/gzip`, at most 50 MB compressed; a `Content-Length` is required, 411 without) — what `foldrun snapshot push` makes. Checked on the server whatever the client did: plain files and folders only (no links, devices or extended headers), no path that leaves the folder or differs from another only by case, at most 20,000 entries, 10 MB a file and 200 MB unpacked, and no secret — `422` naming the file and line, never the value. Answers `{ snapshotId, files, bytes, compressedBytes, expiresAt, reused }`: `201`, or `200` when this project already had this exact folder (`reused`; stored once by its hash). Usable only in this project; kept 7 days from the last send, and as long as a run that uses it is kept. An account holds at most 50 snapshots and 2 GB (`422` past either). Needs `snapshot:write` (editor). Idempotent |
|
|
209
209
|
| `/api/workspaces/<ws>/evals` | GET, POST | list; create (`name`) |
|
|
210
|
-
| `/api/workspaces/<ws>/evals/trends` | GET | evals by change, the
|
|
210
|
+
| `/api/workspaces/<ws>/evals/trends` | GET | evals by change, the project Observe page's table: `{ workspace, trends: [{ eval, latest, previous, delta }] }`, biggest drop first. `latest` is the eval's newest run and `previous` the most recent run on a DIFFERENT commit (`null` when every run so far was on one) — each `{ eval, at, commit, passed, failed, costUsd }`, `commit` a git sha or a revision id (`r-…`), `null` when no change is on record; `delta` is passed now minus passed then, `null` without a previous. Not windowed: two runs on one commit differ only by the model, so the comparison is always against another commit |
|
|
211
211
|
| `/api/workspaces/<ws>/evals/<eval>/run` | GET, POST | POST runs one eval and answers with its result; with `{ async: true }` it answers `202 { started, eval, runId, startedAt }` at once and the eval runs on — an eval of slow cases outlives a proxy's read timeout (Cloudflare's is 125 s by default). One run of an eval at a time: a second is `409` naming the run that holds it. `GET ?run=<runId>` is what to poll — that run alone, whatever else runs or writes the eval's latest result meanwhile: `{ runId, state, running }` where `state` is `running`, `done` (with its `result`), `failed` (with `error`), `lost` (it stopped reporting before saving a result, e.g. a restart) or `unavailable` (an id not on record — the last 20 runs are kept). Plain `GET` answers who holds the eval now (`running`, `runId`, `startedAt`) and the latest `result`. The dashboard and `foldrun eval --to` start async and poll by run id |
|
|
212
|
-
| `/api/workspaces/<ws>/evals/<eval>/compare` | GET, POST | compare models on one eval: its cases under two to four settings, side by side. `POST { configs: [{ model, effort?, agent? }], repeat?, maxUsd? }` — `model` a tier (`fast`, `default`, `max`) or a model id; `effort` low…max; `agent` (flow evals) forces only that agent's steps, else every step; `repeat` 1–5 (1); `maxUsd` the spend limit, above 0 and at most 100 (5). At most 60 runs (cases × settings × repeat, else `413`). Answers `202 { started, eval, runId, startedAt, trials, maxUsd }` and runs on: every run a test run, the eval's own judge for all. `GET ?run=<runId>` → `{ runId, state, running }` — `running` (with `progress: { done, total }`), `done` (with `result`), `failed` (with `error`), `lost` or `unavailable`. `result` is `{ eval, target, judge, startedAt, finishedAt, repeat, maxUsd, spentUsd, stopped, configs: [{ model, effort, agent, label, trials, passed, notRun, rate, costUsd (runs and judges), judgeCostUsd, avgCostUsd, avgSecs (worker pick-up to end), runIds }], cases: [{ case, passed: [per setting], trials: [per setting] }] }`. Plain `GET` → `{ running, runId?, startedAt?, progress?, comparisons }` (the last 20, newest first). One comparison of an eval at a time (`409`), none while the account or
|
|
213
|
-
| `/api/workspaces/<ws>/evals/<eval>/improve` | POST | ask for a proposed fix now: for a grader, from its failed grades no proposal has covered; for an eval that runs cases, from its last result's failed cases. Answers `202` with the proposal, `status: "drafting"` — the assistant drafts it (one reply, paid as Ask AI's are); poll `GET …/proposals/<id>`. `409` when there is nothing to fix, a proposal for this eval is open, or the account or
|
|
212
|
+
| `/api/workspaces/<ws>/evals/<eval>/compare` | GET, POST | compare models on one eval: its cases under two to four settings, side by side. `POST { configs: [{ model, effort?, agent? }], repeat?, maxUsd? }` — `model` a tier (`fast`, `default`, `max`) or a model id; `effort` low…max; `agent` (flow evals) forces only that agent's steps, else every step; `repeat` 1–5 (1); `maxUsd` the spend limit, above 0 and at most 100 (5). At most 60 runs (cases × settings × repeat, else `413`). Answers `202 { started, eval, runId, startedAt, trials, maxUsd }` and runs on: every run a test run, the eval's own judge for all. `GET ?run=<runId>` → `{ runId, state, running }` — `running` (with `progress: { done, total }`), `done` (with `result`), `failed` (with `error`), `lost` or `unavailable`. `result` is `{ eval, target, judge, startedAt, finishedAt, repeat, maxUsd, spentUsd, stopped, configs: [{ model, effort, agent, label, trials, passed, notRun, rate, costUsd (runs and judges), judgeCostUsd, avgCostUsd, avgSecs (worker pick-up to end), runIds }], cases: [{ case, passed: [per setting], trials: [per setting] }] }`. Plain `GET` → `{ running, runId?, startedAt?, progress?, comparisons }` (the last 20, newest first). One comparison of an eval at a time (`409`), none while the account or project is paused (`409`); a grader, saved inputs or an eval with a `run:` check `400`. Needs `run:start` to start |
|
|
213
|
+
| `/api/workspaces/<ws>/evals/<eval>/improve` | POST | ask for a proposed fix now: for a grader, from its failed grades no proposal has covered; for an eval that runs cases, from its last result's failed cases. Answers `202` with the proposal, `status: "drafting"` — the assistant drafts it (one reply, paid as Ask AI's are); poll `GET …/proposals/<id>`. `409` when there is nothing to fix, a proposal for this eval is open, or the account or project is paused. Held to Ask AI's limits — the same per-person hourly count (`429`), and on the platform's models its daily account count (`429`) and the balance (`402`). Needs `run:start` |
|
|
214
214
|
| `/api/workspaces/<ws>/evals/<eval>/grades` | GET | a grader's grades (an eval with `trigger: runs`): `{ eval, flow, agent, sample, improve, days, summary, grades }`. `summary` is the window's `{ graded, passed, failed, errors, rate, costUsd, byDay: [{ day, graded, passed, failed }] }` (`rate` is passed ÷ decided, `null` when nothing was decided); `grades` the newest first, one per run — `{ eval, runId, flow, at, status (pass, fail or error — not decided), checks: [{ name, passed, error?, assertions: [{ type, value, passed, detail }] }], costUsd (the judges'), model, evalRevision, runRevision, runFinishedAt, by }`. `?days=` 1–90 (30), `?status=` pass, fail or error, `?limit=` 1–500 (100). An eval that runs cases is `400` |
|
|
215
|
-
| `/api/workspaces/<ws>/evals/<eval>/grade` | POST | grade one finished run now, sampled or not: `{ run }` → the grade (the shape above), kept like any other — the newest grade of a run is the one shown. Needs `run:start`; the judges run on the account's model key. A run that is not this grader's (another flow, or no step by its agent) is `400`, a run still going `409`, one with no reply to grade `409`, an eval that runs cases `400`, a paused account or
|
|
215
|
+
| `/api/workspaces/<ws>/evals/<eval>/grade` | POST | grade one finished run now, sampled or not: `{ run }` → the grade (the shape above), kept like any other — the newest grade of a run is the one shown. Needs `run:start`; the judges run on the account's model key. A run that is not this grader's (another flow, or no step by its agent) is `400`, a run still going `409`, one with no reply to grade `409`, an eval that runs cases `400`, a paused account or project `409` |
|
|
216
216
|
| `/api/workspaces/<ws>/tools/<tool>/test` | POST | exercise one tool (`args`, `path`). An http tool with an `operations:` allowlist is probed only with a GET to one of its operations (no `path`: the first GET without parameters), and fails if the allowlist resolves nothing, as a run does |
|
|
217
|
-
| `/api/workspaces/<ws>/hooks` | GET | the [hooks](hooks) this
|
|
217
|
+
| `/api/workspaces/<ws>/hooks` | GET | the [hooks](hooks) this project can turn on — its own and the library's (shadowing marked), invalid ones with the reason, and who turns each on — plus `recent`: every deny, rewrite and failure hooks wrote in the last `?runs=` runs (1–500, default 50), newest first; `?all=1` includes notes and context |
|
|
218
218
|
| `/api/workspaces/<ws>/hooks/<name>/test` | POST | run one [hook](hooks) on a sample event: body `{ event }`, answer the hook's own (`ok`, `decision`, `reason`, `input`, `context`, `reply`, `note`, `failure`, `ms`). Shares the `hooks/` path with flow webhooks below — `/test` is only ever a hook's. Answers `404` for no such hook, `422` for an invalid `hook.md`, `400` for an event that is not an object. On an isolated install hook code never runs in the platform's own process, so this answers with where to test it instead (`foldrun hook test` locally, or a test run) |
|
|
219
219
|
|
|
220
220
|
Running an agent alone is the fastest way to test a prompt change without
|
|
@@ -224,11 +224,11 @@ paying for the steps around it.
|
|
|
224
224
|
|
|
225
225
|
| Route | Methods | |
|
|
226
226
|
|---|---|---|
|
|
227
|
-
| `/api/workspaces/<ws>/runs?limit=&before=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }], next }`, newest first; `next` is the cursor for the page after (`<startedAt>~<runId>`, null on the last page) — pass it back as `before`, which also takes a time (runs that started before it) or a run id of the
|
|
228
|
-
| `/api/workspaces/<ws>/runs/<id>/calls/<call>` | GET | one tool call's recorded content (see [Runs](runs#what-a-run-records)); needs `workspace:write` (an editor or above — a viewer sees the run but not what its tools were given and returned): `{ call: { id, tool, input, output, inputChars, outputChars, truncated, inputCut, outputCut } }` — what it was given and what it gave back, secrets masked, each at most 65,536 characters; `inputChars`/`outputChars` are the whole length, `inputCut`/`outputCut` say which part was cut (`truncated`: either). `<call>` is the tool event's `call`; an event with `captured: true` has content here. 404 when nothing was recorded: the
|
|
227
|
+
| `/api/workspaces/<ws>/runs?limit=&before=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }], next }`, newest first; `next` is the cursor for the page after (`<startedAt>~<runId>`, null on the last page) — pass it back as `before`, which also takes a time (runs that started before it) or a run id of the project (runs older than it); a position, not an offset, so runs starting meanwhile shift nothing and one cursor pages every project (`foldrun runs --before`, `--page`, `--all`); a `before` that is none of these is a `400`; search (see [Runs](runs#searching-runs)) with `tool` (a step called a tool whose name contains it), `tool_error=1`, `agent`, `model` (contains), `min_tokens` (`50k`), `min_secs`, `customer` (one end customer's runs, exactly), `context` (one [conversation](runs#conversations)'s runs, its id exactly; each run in it carries `context: { id, key, a2a? }`) — `limit` counts the matches — `verdict` is the word the summary leads with (`GOOD`, `QUIET`, `BLOCKED`, `BAD` or null) and `outcome` the one word every page shows (`running`, `queued`, `waiting`, `good`, `done`, `quiet`, `blocked`, `bad`, `failed`, `stopped`); `failure` is why a run failed (null otherwise) — `{ agent, reason, class, kind, message, fix }` and, for a limit, `used`, `allowed`, `unit` and `scope`, for a refused site `host` (see [Runs](runs#why-it-failed)), `chargedUsd` is what the account was charged for the run (one credit is one cent), null until the ledger settles it, while `costUsd` is the provider's token cost — off the run index (see [Runs](runs#the-runs-list)); a finished run's steps carry `agent`, `status`, `costUsd` and `tokens` (`{ input, output, cacheRead, cacheWrite }`, see [Runs](runs#the-record)), and the run its summed `tokens` — not their reply or trace |
|
|
228
|
+
| `/api/workspaces/<ws>/runs/<id>/calls/<call>` | GET | one tool call's recorded content (see [Runs](runs#what-a-run-records)); needs `workspace:write` (an editor or above — a viewer sees the run but not what its tools were given and returned): `{ call: { id, tool, input, output, inputChars, outputChars, truncated, inputCut, outputCut } }` — what it was given and what it gave back, secrets masked, each at most 65,536 characters; `inputChars`/`outputChars` are the whole length, `inputCut`/`outputCut` say which part was cut (`truncated`: either). `<call>` is the tool event's `call`; an event with `captured: true` has content here. 404 when nothing was recorded: the project says `capture: metadata`, or the run is from before 19 Oct 2026. 502 when it was recorded but cannot be read now (the object store or the database is unavailable) — never an empty answer. A run's steps also carry `calls`, each model call (`n`, `at`, `ms`, `model`, `stop`, `tokens`, `tools`, and `subagent` / `attempt` when a sub-agent or a later attempt made it); a step that handed jobs to `sandbox: own` sub-agents carries `delegations` (`id`, `agent`, `status`, `costUsd`, `ms`), and each job is a step of its own with `subagentOf` (the delegating agent), `delegation` (that `id`) and `wrote` (the project paths it changed — copied into the delegating step's sandbox too, up to 4 MiB a job); and the run its `revision` (the project's latest revision when a worker picked it up — a deploy's commit, or the id an edit through `/source` was saved as) and `drivenAt` (when that was) |
|
|
229
229
|
| `/api/workspaces/<ws>/runs/<id>/trace` | GET | the run as one tree (see [Runs](runs#the-trace-tree)): `{ tree, failure }`. Each span is `{ id, kind, label, start, end, status, children, … }`, where `kind` is `run`, `step`, `model` (one model call: `model`, `stop`, `tokens`), `tool` (`call`, `captured` when its input and output were recorded) or `error` (`text`); `start`/`end` are epoch milliseconds and `status` is `ok`, `error`, `running`, `waiting`, `skipped` or `pending`. A tool call sits under the model call that asked for it. `failure` is the ids from the root to the first thing that went wrong, which the run page opens on; `[]` when nothing did |
|
|
230
230
|
| `/api/workspaces/<ws>/runs/<id>/compare?with=` | GET | this run beside another of the same flow (see [Runs](runs#compare-with-the-last-good-run)): `{ comparison: { base, run, revisionChanged, changedFiles, steps }, chosen }`. Each step is `{ step, agent, base, run, changes }`: both sides' status, instruction, model, seconds, tokens, model calls, tool counts, tool errors, first errors and first line said, and `changes` in words (`status: completed → failed`, `new error: …`, `instruction changed`, `tools: +web ×3`, `took 12s → 48s`, …). `changedFiles` lists the files changed between the revisions the two ran (null when one is unknown). `with` names the other run; unasked it is the newest earlier run of the flow that finished well, else the run this one re-ran (`chosen` says which) |
|
|
231
|
-
| `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, its money — `chargedUsd` (what the account was charged, the ledger's line; `null` until the run settles: the worker settles it as it ends, and an hourly pass retries one that failed to), `estimatedUsd` (its list price, the figure until then) and `settled` — `failure` (why it failed, the same object the runs list gives — see [Runs](runs#why-it-failed); null when it did not), the runner `image` it ran on and — for a step that browsed through the account's pod from slim — its `browserPod` reconnects and fallback ([runs](runs#the-record)). `?wait=true&timeout=<s>` instead blocks until the run stops (or `timeout`, default 300, max 900) and answers the verdict the run routes give — `200` once the run has ended, however it ended: `ok: true` when it completed, `ok: false` with its `status` and `failure` when it failed or was stopped (a run that fails is the answer, not a fault in the call — it was a `500` before 29 Oct 2026); `202` still going (`timedOut`) or parked on a person (`awaitingApproval`). A start refused before any run exists — a paused account or
|
|
231
|
+
| `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, its money — `chargedUsd` (what the account was charged, the ledger's line; `null` until the run settles: the worker settles it as it ends, and an hourly pass retries one that failed to), `estimatedUsd` (its list price, the figure until then) and `settled` — `failure` (why it failed, the same object the runs list gives — see [Runs](runs#why-it-failed); null when it did not), the runner `image` it ran on and — for a step that browsed through the account's pod from slim — its `browserPod` reconnects and fallback ([runs](runs#the-record)). `?wait=true&timeout=<s>` instead blocks until the run stops (or `timeout`, default 300, max 900) and answers the verdict the run routes give — `200` once the run has ended, however it ended: `ok: true` when it completed, `ok: false` with its `status` and `failure` when it failed or was stopped (a run that fails is the answer, not a fault in the call — it was a `500` before 29 Oct 2026); `202` still going (`timedOut`) or parked on a person (`awaitingApproval`). A start refused before any run exists — a paused account or project (`423`), an agent or flow that is not there (`404`), `overlap: skip` (`409`) — is answered as such and waits for nothing. Ask in short pieces: whatever sits in front of the platform cuts a request that stays silent too long (Cloudflare at 100 s, an AWS ALB at 60 s), and a flow can run for many minutes — the CLI's `--wait` asks 25 s at a time and comes back here on every `202`. DELETE erases the run's record and archived outputs (a run still going is stopped first; the ledger line stays) and needs `workspace:manage` — an admin — since 30 Oct 2026 (it was `run:start`) |
|
|
232
232
|
| `/api/workspaces/<ws>/runs/<id>/stream` | GET | server-sent events, live: `run` (the whole record, each time it changes), every event has an `id:` — the cursor, each step's event count (`v1.3-0`). With `?delta=1` the first `run` event is the whole record and after it each `delta` event carries only what changed: the run's own fields, and `steps` as `{ <index>: the step without its events, plus events (the new ones) and from (the first new one's index) }`; a reconnect that sends `Last-Event-ID` gets a delta from that cursor, not the record again (a cursor that no longer fits gets the whole record). `done` (`{ status, chargedUsd, estimatedUsd, settled }` — usually not settled yet; the run's GET has the charge once it is) at the end. A stream that cannot start is refused like every other route — `401`/`403`/`404` with `{ error }` JSON (before 5 Nov 2026 it was plain text). The dashboard's run page and `foldrun logs --follow` (and `invoke --watch`, `agent run --wait`) read it |
|
|
233
233
|
| `/api/workspaces/<ws>/runs/<id>/stop` | POST | destroys the sandbox, not just the record. `404` for no such run, `409` for one already finished |
|
|
234
234
|
| `/api/workspaces/<ws>/runs/<id>/rerun` | POST | again — `step` to start partway, or `agent` to start at the first step that agent runs (one of the two is required). `instruction` tells that step something else this once, in place of the flow's (the flow file is not changed); the new run's `rerunOf` says `{ run, step, instruction }`. Takes `?wait=true&timeout=` like a flow start. `404` for no such run, `409` for one not finished, `400` for a `step` that is not a whole number |
|
|
@@ -240,13 +240,13 @@ paying for the steps around it.
|
|
|
240
240
|
| `/api/workspaces/<ws>/runs/<id>/archive` | GET | one file the run archived from an agent's `outputs/` — `agent` and `path` name it; the run page's Out column links here, and plays a recording or shows a picture inline. Served as bytes, never as a page; a `Range` header gets `206` with that slice, which is how a video seeks |
|
|
241
241
|
| `/api/workspaces/<ws>/runs/<id>/live` | GET | the live view: with no query, `{ agents: { <agent>: <last frame at> } }`; with `agent=`, the newest frame that agent's browser streamed as `image/jpeg` (or `204` when there is none), and `x-live-url`, `x-live-at`, `x-live-ended`, `x-live-engine` headers. Frames arrive from `web action=browse` through the step's egress lease and expire five minutes after the last |
|
|
242
242
|
| `/api/workspaces/<ws>/runs/<id>/promote` | POST | save a finished run as a regression case in `evals/<target>-regressions.md` — `evalName` to pick the file, `caseName` to name the case, `expect` (assertion lines, e.g. `["contains: $34"]`) to replace the default judge. A run that went wrong (failed, BLOCKED or BAD) needs `should` — what it should have done, the judge's claim for the case — or `expect`: its own answer is not the one to keep. Returns `{ ok, file, created, caseName }` |
|
|
243
|
-
| `/api/workspaces/<ws>/triggers?days=` | GET | why nothing happened: one row per flow saying how often its trigger fired, how often that became a run, and what the difference was — a duplicate delivery, a throttled burst, a debounced burst still being waited out, a quarantined flow, a
|
|
244
|
-
| `/api/workspaces/<ws>/notify/deliveries` | GET | the outbound webhook log: every `notify:` url delivery from this
|
|
243
|
+
| `/api/workspaces/<ws>/triggers?days=` | GET | why nothing happened: one row per flow saying how often its trigger fired, how often that became a run, and what the difference was — a duplicate delivery, a throttled burst, a debounced burst still being waited out, a quarantined flow, a project or account paused by a person (`halted`), an `overlap: skip`, a fire missed while the platform was down. Plus every decision newest-first, and the hook/inbox delivery log, which answers the separate question of whether a request arrived and was authentic. `days` 1–365, default 7 (`since=`, its older name, still works — deprecated) |
|
|
244
|
+
| `/api/workspaces/<ws>/notify/deliveries` | GET | the outbound webhook log: every `notify:` url delivery from this project, newest first — `{ deliveries, total, limit, offset, endpoint }`. A delivery is `{ id, event, status, destination, attempts, attemptLog, lastStatusCode, lastError, nextAttemptAt, createdAt, updatedAt, body }`: `id` is the `X-Foldrun-Delivery` header; `status` is `pending` (a retry is due at `nextAttemptAt`), `delivered`, `failed` (gave up after six attempts) or `skipped` (the endpoint was switched off); each attempt is `{ n, at, statusCode, durationMs, response (first 500 characters), error, manual? }`. `body` is what was sent, except that a gate's `approveUrl`/`rejectUrl` (top level and in `links`) read `[redacted]` — they decide without a login, and this log is readable by every role; the receiver still gets them, on a redelivery too. `?status=`, `?event=`, `?limit=` (50, at most 200), `?offset=`. `endpoint` is `{ failingSince, lastSuccessAt, lastFailureAt, disabledAt, disabledReason }` or null. Kept 30 days |
|
|
245
245
|
| `/api/workspaces/<ws>/notify/deliveries/<id>/redeliver` | POST | send one delivery again now — the same id and body, signed afresh, to the URL `notify:` names today. `{ ok, attempt, delivery }`, always `200` when the delivery exists (whether the receiver took it is the answer); `404` when it does not. An accepted redelivery switches a disabled endpoint back on. Needs the permission that runs |
|
|
246
|
-
| `/api/workspaces/<ws>/notify/test` | POST | sends one real notification to whatever this
|
|
246
|
+
| `/api/workspaces/<ws>/notify/test` | POST | sends one real notification to whatever this project's `notify:` resolves to, and answers `{ ok, destination, detail }` — including the provider's own words when it failed, which are what name the problem. Always `200`: the request was handled, and the result is the answer — except past 10 test sends an hour for one project, a `429` with `Retry-After`. Needs the permission that runs, because it sends real mail |
|
|
247
247
|
| `/api/workspaces/<ws>/observe?days=` | GET | the observability report the Observe page renders — `tally` (the shared outcome counts) and `chargedUsd` beside `costUsd` on the report, each flow, day and agent (what was charged, the ledger's line or list price until settled, versus the provider's token cost); per-agent failures, retries, tokens, `cacheHitRate`, `turns` and `systemPromptChars` (each `{ n, p50, p95, max }`), per-tool calls/errors/latency and `resultSize` (characters per result, same shape), `resultChars` (their sum) and `heavyCalls` (results over 10,000 characters), per-flow duration, day series, recent failures, and `startup` — one row per start-up phase in order, `{ phase, took, from, at, parallel, waited }`, the four spreads each `{ n, p50, p95, max }` in seconds (`took` is the phase's own share, from when it could begin to when it ended; `from` when it began and `at` when it ended, counted from the step's start; percentiles need five samples). The search and browser pods boot beside the step pod, so on a cold run `services` ends after `ready` and `files`: it is then a parallel lane from 0 — `parallel` counts the steps where it was — the step pod's phases keep their own shares, and `go` starts once services is up, `waited` being how long it was held (0 on every other phase). `days` 1–365, default 30 (`since=`, its older name, still works — deprecated) |
|
|
248
|
-
| `/api/workspaces/<ws>/history?path=&id=&limit=` | GET | every change to the
|
|
249
|
-
| `/api/workspaces/<ws>/restore` | POST | put the
|
|
248
|
+
| `/api/workspaces/<ws>/history?path=&id=&limit=` | GET | every change to the project, newest first — `path` narrows to one file, `id` returns one revision with its before/after and a line diff, `limit` 1–500, default 100. A deploy's revision id is its commit |
|
|
249
|
+
| `/api/workspaces/<ws>/restore` | POST | put the project's source back as it was at a point in its history. `to`: a revision id (`r-…`), the commit a deploy named (or its prefix), an ISO date/time (the last revision at or before it) or an age (`90m`, `12h`, `3d`, `2w`) — every revision since 17 Oct 2026 holds a snapshot of the whole source. `{ to, dryRun: true }` answers `{ to: { id, sha, at, by, message }, from, added, updated, removed, files: [{ path, change, diff }], blockedBy, noop, issues, warnings }` and writes nothing; `issues` are the deploy checks that would refuse that tree, `warnings` the ones it would deploy with. The restore needs `confirm` set to the project's name (400 without) and takes the dry run's `expectRemoved`; it deploys that revision's snapshot as a new revision (undo: restore to `from`; `to.sha` is the same id as `to.id`, kept from when revisions were git commits), keeps runs, `state/`, storage, secrets and agent-written memory, and is refused 409 while runs are in flight or when it would remove something not in `expectRemoved`. `workspace:write`, and `workspace:manage` when the restored `AGENTS.md` has different policy keys (`403` naming them; a dry run is not refused); audited as `workspace.restored` |
|
|
250
250
|
|
|
251
251
|
`status` is one of `queued`, `running`, `awaiting-approval`, `completed`,
|
|
252
252
|
`failed`.
|
|
@@ -293,7 +293,7 @@ when a person presses Run, not on every push.
|
|
|
293
293
|
The usual loop: `runs` to find it → `runs/<id>` to see which step failed and
|
|
294
294
|
what it cost → fix the markdown → `deploy` → `rerun`.
|
|
295
295
|
|
|
296
|
-
## Storage —
|
|
296
|
+
## Storage — project files agents produce
|
|
297
297
|
|
|
298
298
|
**A request body is at most 10 MB.** Anything larger is refused with `413`
|
|
299
299
|
before it reaches a route — it is never passed on cut short. Larger files go
|
|
@@ -306,7 +306,7 @@ one; a body that does not match the length it declared is a `400`.
|
|
|
306
306
|
|
|
307
307
|
| Route | Methods | |
|
|
308
308
|
|---|---|---|
|
|
309
|
-
| `/api/workspaces/<ws>/storage` | GET, POST, PUT, DELETE | `404` when the
|
|
309
|
+
| `/api/workspaces/<ws>/storage` | GET, POST, PUT, DELETE | `404` when the project does not exist. GET lists every stored file with the quota; POST records one (`path`, `sha`, `size` — the record takes the length the store reports, not this; over the per-file limit or the quota the object is removed and the call refused); PUT `?path=` writes one; DELETE `?path=` removes one |
|
|
310
310
|
| `/api/workspaces/<ws>/storage/download?path=` | GET | a redirect to a presigned URL |
|
|
311
311
|
| `/api/workspaces/<ws>/storage/upload-url` | POST | a presigned PUT (`path`, `sha`, and `size` — the length in bytes; since 30 Oct 2026 the limits are checked on it and it is signed into the URL, so the bucket refuses any other length. Optional for older clients: registering the upload measures the real object against the same limits either way) |
|
|
312
312
|
| `/api/workspaces/<ws>/storage/preview?path=` | GET | the file parsed for reading, as JSON — text, a table, a document, slides, an archive listing, a mesh, a hex dump. Stored HTML and SVG come back as strings for a sandboxed frame, never served as pages. `413` over 25 MB |
|
|
@@ -336,14 +336,14 @@ up. Each refusal carries a `code` (`unsupported`, `too_large`, `unreadable`,
|
|
|
336
336
|
| Route | Methods | |
|
|
337
337
|
|---|---|---|
|
|
338
338
|
| `/api/extract?name&lang&ocr&engine&wait` | POST | a file to text, sent whole as the raw request body with a `Content-Length` (at most 10 MB, the API's per-request limit — a larger file goes to storage first and through `storage/extract`). `name` the file's name (a hint; the bytes decide), `lang` `fa`, `en` or `auto` (OCR `fas+eng` or `eng`; speech in that language or the one heard), `ocr` `auto` (only pages with no text layer), `always` or `never`, `engine` `docling` for a PDF read by Docling. Answers `{ sha256, kind, format, text, pages?, ocrPages?, seconds?, confidence?, language?, engine: { parser, speech? }, truncated, warnings, cached, ms }`; speech comes under `[audio · m:ss · transcript, fa]`, a video's as `[video · m:ss · speech]` then its on-screen text. The file is not stored. What starting a run needs (`run:start`). Idempotent |
|
|
339
|
-
| `/api/extract/<id>` | GET | one extraction that answered `202`: `{ id, status, result?, error?, wrote?, createdAt, finishedAt }` — `status` `running`, `done` (with `result`) or `failed` (with `error: { status, code, message }`; `worker_stopped` when the server working on it stopped). The account's own; a member or key scoped to some
|
|
339
|
+
| `/api/extract/<id>` | GET | one extraction that answered `202`: `{ id, status, result?, error?, wrote?, createdAt, finishedAt }` — `status` `running`, `done` (with `result`) or `failed` (with `error: { status, code, message }`; `worker_stopped` when the server working on it stopped). The account's own; a member or key scoped to some projects reads the jobs of those and the account-level ones it started. Kept a day |
|
|
340
340
|
| `/api/workspaces/<ws>/storage/extract` | POST | a stored file to text: `{ path, lang?, ocr?, engine?, write?, wait? }`. With `write` (the default, `workspace:write`) the text is written to `<path>.txt` beside the file once it is done — also when the caller stopped waiting — and the answer says `wrote: "<path>.txt"`; a `.txt` is refused. `write: false` only reads (`workspace:read`). Same answers as `/api/extract`, plus `wrote`. Idempotent |
|
|
341
341
|
|
|
342
342
|
## Shares — a public link to one file
|
|
343
343
|
|
|
344
344
|
| Route | Methods | |
|
|
345
345
|
|---|---|---|
|
|
346
|
-
| `/api/workspaces/<ws>/shares` | POST, GET, DELETE | mint (`path`, `ttlDays`: days, `null` never; returns `url`, `token`, `id`, `path`, `contentType`, `expiresAt`), list, revoke (`?token=` or `?id=`, only a link of this
|
|
346
|
+
| `/api/workspaces/<ws>/shares` | POST, GET, DELETE | mint (`path`, `ttlDays`: days, `null` never; returns `url`, `token`, `id`, `path`, `contentType`, `expiresAt`), list, revoke (`?token=` or `?id=`, only a link of this project) |
|
|
347
347
|
| `/s/<token>` | GET, HEAD | the file itself, no credential, streamed; HEAD reads only its length. `Cache-Control: private, no-store`, so no shared cache serves a link after it is revoked or expires. `429` past 120 a minute from one caller or 1,200 a minute for one link |
|
|
348
348
|
|
|
349
349
|
From the terminal: `foldrun storage share <path>`, `shares`, `unshare <token|id>`.
|
|
@@ -359,7 +359,7 @@ and is never derived from the path. `createdBy` is the caller (a person's
|
|
|
359
359
|
email, or the key), never a name the request sends.
|
|
360
360
|
|
|
361
361
|
Only `storage/`, `files/` and `outputs/` can be shared. An agent talked into
|
|
362
|
-
sharing something is confined to what the
|
|
362
|
+
sharing something is confined to what the project produced and can never
|
|
363
363
|
hand out `memory/`, an agent's prompt, or a credential.
|
|
364
364
|
|
|
365
365
|
Links expire in 7 days unless `ttlDays` says otherwise (`null` never expires).
|
|
@@ -379,7 +379,7 @@ its header and requires a URL it can GET for itself.
|
|
|
379
379
|
|
|
380
380
|
| Route | Methods | |
|
|
381
381
|
|---|---|---|
|
|
382
|
-
| `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a
|
|
382
|
+
| `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a project's own store; unsaid is the account's, which a key scoped to some projects may not touch. `name` is a string (400 otherwise). The account's `RESEND_API_KEY` and `EMAIL_FROM` — the sender of everyone's sign-in mail — are set, rebound and deleted by the owner alone (403 to anyone else), here and through an OAuth connect — the owner signed in, in the browser: no key, not even their own `foldrun login` one. An oauth2 recipe from a caller scoped to some projects links to the account's saved OAuth app with the same token URL and client id but never saves or changes one (as `POST /api/oauth/clients` refuses them). PATCH also takes `workspaces` (with or instead of `sites`): `{ name, workspaces: ["sales", "ops"] }` limits an **account** secret to those projects — every other one finds it not set, in runs, tool tests, `notify:` (its email too), the egress proxy and MCP, for runs that start after it ([limited to some projects](secrets#limited-to-some-projects)); `null` opens it to every project, `[]` to none; the answer carries `workspaces` (sorted, or `null`). `ifWorkspaces` — the list you loaded, `null` for every project — makes it conditional: 409 when the list changed since, nothing written. PUT takes the same `workspaces` and saves it with the value in one write (the answer carries it too); it is never ignored. Account store only (400 with `workspace`), an admin over every project (403 for a scoped caller), names of projects that exist, checked under the vault's lock (400 otherwise), 404 for a secret that is not there; audited as `secret.workspaces` (PATCH) and in `secret.set` (PUT). GET of the account store lists each limited secret's `workspaces`, and `?workspace=` leaves out an account secret that project may not use. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set`. PUT also takes `token_exchange: { token_url, client_id, client_secret?, token_auth?, subject_secret, subject_token_type?, requested_token_type?, audience?, resource?, scope? }`: a secret whose value is another secret's token traded at a token endpoint (RFC 8693); its `kind` is `token-exchange`. Deleting an `oauth2` secret, or replacing one with a PUT, revokes the old grant at the provider (RFC 7009) when its recipe has a `revocation_url`. The secret is written or deleted first, then the old grant is revoked, and the answer carries `revoked: { skipped?, revoked: [refresh_token, access_token], error? }`. `skipped` is `no-revocation-url`, `shared-grant` (another secret holds the same refresh token, or a grant from the same app; providers such as Google revoke per app, so it is kept), `same-app` (the replacement is from the same app, so revoking would end it too) or `unreadable`. A refusal is reported in `error` and never undoes the write. The recipe's `token_auth` (`client_secret_post`, `client_secret_basic`, `none`, `private_key_jwt` with `client_assertion_key`) and `revocation_url` are kept with it. `oauth2.generate_key: true` with `private_key_jwt` makes the key, and the answer carries `public_jwk` |
|
|
383
383
|
|
|
384
384
|
`PUT` takes `name` plus exactly one shape: `value` (a string), `file` (a PEM,
|
|
385
385
|
a cert), `oauth2`, `service_account`, `ssh`, `api`, `client_cert` (`{ cert, key, passphrase?, export? }` — mutual TLS, presented by the egress proxy to the exact sites the secret is bound to), or `identity` (`{ audience }` — keyless cloud access). They go to the vault;
|
|
@@ -391,46 +391,46 @@ Reads return which secrets exist, never their values.
|
|
|
391
391
|
|
|
392
392
|
| Route | Methods | |
|
|
393
393
|
|---|---|---|
|
|
394
|
-
| `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`. A key's prefix says what it is: `fr_api_` an API key, `fr_a2a_` an A2A key (`fr_dep_` is reserved for deploy keys); keys minted before 11 Nov 2026 start `mda_` (or `mdk_`) and keep working — a key is looked up by its hash, never its prefix, and `prefix` is its first 12 characters. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must say `a2a: { publish: true }` when the key is minted — a flow not published is refused, 400 — and still say it on every call) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one
|
|
395
|
-
| `/api/keys/<id>` | PATCH | `{ requireCustomer: true \| false }` — whether every run the key starts must name an end customer ([end customers](runs#end-customers)); a run without one is refused `400`, code `customer_required`. Not for an A2A key. An admin of every
|
|
396
|
-
| `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role,
|
|
397
|
-
| `/api/team` | GET, POST | members with their roles and
|
|
398
|
-
| `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some
|
|
394
|
+
| `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`. A key's prefix says what it is: `fr_api_` an API key, `fr_a2a_` an A2A key (`fr_dep_` is reserved for deploy keys); keys minted before 11 Nov 2026 start `mda_` (or `mdk_`) and keep working — a key is looked up by its hash, never its prefix, and `prefix` is its first 12 characters. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must say `a2a: { publish: true }` when the key is minted — a flow not published is refused, 400 — and still say it on every call) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one project is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
|
|
395
|
+
| `/api/keys/<id>` | PATCH | `{ requireCustomer: true \| false }` — whether every run the key starts must name an end customer ([end customers](runs#end-customers)); a run without one is refused `400`, code `customer_required`. Not for an A2A key. An admin of every project; audited as `apikey.require_customer`. `POST /api/keys` takes `requireCustomer` too |
|
|
396
|
+
| `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, projects and deploy scope — and, when it had an end, the same lifetime from today — returned once like a mint (`{ ok, key, id, prefix, role, workspaces, expiresAt, replaced: { id, endsAt } }`). `grace`: `0` (default — the old key is revoked at once), or a duration up to `7d` such as `1h` or `24h`, during which the old key still works and after which it is refused as expired. A key is rotated once: rotating a key already replaced is 409 `this key was already rotated to <prefix>…; rotate that one` — and someone who lost the new key's secret rotates the NEW key, which mints another and ends the lost one (rotating the old one again would leave the lost key working). Two rotations of one key at once mint one key. `keys:manage`; a key outside the caller's scope is 404 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, projects and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). A retry with the old key inside those 10 minutes — the CLI lost the answer, or could not store it — rotates that replacement instead, when nobody has used it and it is at least 30 seconds old (a younger one is a 409: another command may have just stored it). That is how the CLI renews its sign-in; any other key rotating itself still needs `keys:manage`. Audited as `apikey.rotated` (`self: true` for a self-rotation). A `foldrun login` key stays one only when it renews itself or its own person rotates it, signed in; rotated by any other caller the new key is an ordinary one |
|
|
397
|
+
| `/api/team` | GET, POST | members with their roles and project scope; mint an invite (a session, or the person's own `foldrun login` key, which invites no admin) — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
|
|
398
|
+
| `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some projects sees only the invites inside its scope |
|
|
399
399
|
| `/api/team/invites/<id>` | DELETE | revoke an invite: its link stops working at once. `{ ok, revoked, invite }` — `revoked: false` when it was already revoked or expired; `404` for an id that is not this account's; `409` for one already accepted (remove the member instead). `team:manage`, a key included; a scoped caller only inside its scope, and an admin invite only by the owner. Audited as `member.invite_revoked` |
|
|
400
|
-
| `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which
|
|
400
|
+
| `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which projects they may open (`workspaces`: names, or null for all); remove them. A session, or the person's own `foldrun login` key (acting as at most admin). Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer projects revokes the keys and invites that reach beyond their new standing. `404` for an id that is not a member, whatever the body |
|
|
401
401
|
| `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only, signed in, and re-proving it is them: `password` (the current one) and, when two-step sign-in is on, `code` (from the app, or a backup code). 400 without them, 401 when wrong, 6 tries in 15 minutes. You become an admin |
|
|
402
|
-
| `/api/usage/compute` | GET | the account's compute at every level (27 Oct 2026): `compute` is `{ vcpu, memGiB, diskGiB, stepVcpu, stepMemGiB, stepDiskGiB, source }` — the cores, GiB and GiB of disk all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, diskGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some
|
|
403
|
-
| `/api/usage/budget` | GET | spend against the caps, as the Spend limits page shows it (5 Nov 2026): `account` is the account's own `budget:` — `{ budget, label, spentUsd, window }`, `budget` being `{ usd, period }` or `null` for no limit, `label` `"$60/day"` or `null`, `spentUsd` what every
|
|
404
|
-
| `/api/usage/history?days=` | GET | charged spend by flow, by agent and by
|
|
405
|
-
| `/api/account/model` | GET, PUT, DELETE | what every step runs on unless an agent,
|
|
406
|
-
| `/api/account/providers` | GET, POST | GET: the model providers this account's files actually use — each one's preset name, where it is declared, the model a check would send — plus the last daily health check. POST forces one now, which spends one minimal request at each distinct endpoint, and needs the permission that runs and every
|
|
407
|
-
| `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some
|
|
408
|
-
| `/api/usage/rates` | GET | the rates this account is charged now (7 Nov 2026): `rates`, `{ creditUsd, vcpuUsdPerHour, ramUsdPerGibHour, diskUsdPerGibMonth, storageUsdPerGbMonth, networkUsdPerGb, margin }` in dollars, `null` where nothing is billed; `plan`, the account's plan terms (`null` to a caller scoped to some
|
|
409
|
-
| `/api/approvals` | GET | every gate waiting on a person, across
|
|
410
|
-
| `/api/observe?days=` | GET | the account Observe page's analysis, the same function the page renders from: `{ days, timezone, window: { from, to }, previous: { from, to, runs }, kpis, causes, desks, agents, tools, daily }`. `kpis` is the window against the one of the same length before it — `{ runs, finished, succeeded, rate, prevRate, failed, platformFailures, deskFailures, spendUsd, prevSpendUsd, medianSecs }` (`rate` is completed ÷ (completed + failed), `null` with none finished; money is what was charged); `causes` why runs went wrong, the platform's first — `{ kind (platform, verify, timeout, error, blocked, bad, stopped), key, label, platform, count, desks, sample, newest }`; `desks` every
|
|
411
|
-
| `/api/insights?days=&workspace=` | GET | recurring problems found in the runs of the window (see [Runs](runs#insights)): `{ days, insights: [{ id, kind, workspace, agent, tool?, title, why, fix, credits, steps, evidence: [{ workspace, runId, step }] }] }`. `kind` is `cache` (an agent's big prompt mostly uncached), `big-result` (a tool result over 20k characters sent again on every later model call), `retry-loop` (a tool erroring three or more times in a step) or `timeout` (steps using 80% or more of their `timeout:`); `credits` is about what it cost in the window, null when it is not money. `days` 1–30, 7 unasked. A key scoped to some
|
|
412
|
-
| `/api/issues?status=&workspace=` | GET | the account's issues: what went wrong, grouped and kept open until a person resolves it (see [Runs](runs#issues)). One issue is one desk's flow failing at one agent, or ending BLOCKED or BAD, or one platform cause across desks. Each carries `id`, `kind` (`platform`, `failed`, `blocked`, `bad`, `missed` — a scheduled fire that started no run), `status` (`open`, `acknowledged`, `snoozed`, `resolved`), `regressed` and `sinceRevision` (it was resolved and came back, since the revision its new run ran), `snoozedFor`, `workspace`/`workspaces`, `what`, `agent`, `reason`, `action` (what to do), `firstSeen`, `lastSeen`, `count`, the newest `runs`, `recoveredAt` (the flow's newest good run since — it closes nothing), `acknowledged`, `snoozedUntil`, `resolved` and the `history` of what people did. `status` is `active` unasked (open + acknowledged), or `open`, `acknowledged`, `snoozed`, `resolved`, `all`; `workspace` keeps the ones that hit it. A key scoped to some
|
|
413
|
-
| `/api/issues/<id>` | GET POST | one issue; POST acts on it: `{ action: "acknowledge" | "snooze" | "resolve" | "reopen", for?: "30m" | "4h" | "1d" | "1w", until?: ISO, times?: n, note? }` (editor or above), kept in its history with who did it, and answers `{ issue }` as it now stands. A snooze needs `for`, a future `until`, or `times` (until it happens that many more times; with a time too, whichever comes first). A platform issue is the account's: closing it needs access to every
|
|
414
|
-
| `/api/account/export` | GET | the owner's copy of what the platform holds about the account, as one JSON file (`foldrun-<account>-export.json`): `workspaces` (with their flows), `members` (email, role, scope, since), `runs` (an index — id,
|
|
402
|
+
| `/api/usage/compute` | GET | the account's compute at every level (27 Oct 2026): `compute` is `{ vcpu, memGiB, diskGiB, stepVcpu, stepMemGiB, stepDiskGiB, source }` — the cores, GiB and GiB of disk all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, diskGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some projects sees theirs); `workspaces` is each project's own `pool` (its AGENTS.md `compute:`, `null` figures for none) and `inUse`; `runs` is each live run with a pool of its own (its flow's `compute:`) or anything held, `{ workspace, runId, flow, pool, inUse }`; `waiting` lists the steps waiting for room, oldest first — `{ workspace, runId, flow, step, agent, since, why, cpus, memGiB, diskGiB, level?, runPool }`, `since` being when it first found none, its place in line, and `level` the cap that held it when it last looked; `runsWaiting` is `{ waiting, limit, source, slots? }` — the account's runs waiting for their turn (`null` for a caller scoped to some projects) and the most before a new run is refused (`null`: no limit), `source` `install` (`FOLDRUN_MAX_WAITING_RUNS`), `plan` (the account's plan sets it: Free 20, Starter 100, Pro 400, Scale 1,000, defaults the owners confirm) or `derived` (20 × `slots`, the runs it may drive at once, at least 50) ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); `compute.stepDefault`, when present, names the step figures that are the hosted default for an account whose plan sets none. A step past any level waits, with no time limit, and starts in turn; one bigger than a level's whole cap or the step maximum fails at once ([four levels](budgets-and-billing#compute-at-four-levels), [waiting for room](budgets-and-billing#waiting-for-room)) |
|
|
403
|
+
| `/api/usage/budget` | GET | spend against the caps, as the Spend limits page shows it (5 Nov 2026): `account` is the account's own `budget:` — `{ budget, label, spentUsd, window }`, `budget` being `{ usd, period }` or `null` for no limit, `label` `"$60/day"` or `null`, `spentUsd` what every project together has spent in the cap's window (the month's with no cap) and `window` `today`, `this week` or `this month`; `workspaces` is each project's the same way with its name as `workspace`, most spent first. A caller scoped to some projects sees those, and gets `account: null` with `accountHidden: true` — the account's figure is spend over every project. At the cap new runs are refused until the window turns ([four caps](budgets-and-billing#four-caps)) |
|
|
404
|
+
| `/api/usage/history?days=` | GET | charged spend by flow, by agent and by project over time, read from the ledger rather than the run records — so it survives runs being pruned and reports what was billed rather than what was consumed. Buckets by week over three weeks, by day under. Each series carries its periods, its total, and the change between the last two COMPLETE periods, so a partial week never reads as a collapse. `unattributedUsd` is charges from before a line recorded its flow. A caller scoped to some projects sees only the charges in those; `days` 1–365, default 56 |
|
|
405
|
+
| `/api/account/model` | GET, PUT, DELETE | what every step runs on unless an agent, project or the account's AGENTS.md names a `provider:` — the account's own model key, or foldrun's models (the platform's keys for one provider, billed in credits at foldrun's price list; hosted only). GET: `{ set, provider, baseUrl, format, keyHint, runsOn, platformKeyAllowed, source, supply, choiceVersion, foldrunModels }` — never a key, only its last four characters; `runsOn` is `account` (its own key), `foldrun` (foldrun's models for `supply`), `platform` (the platform's credential, for the operator's accounts), `subscription` (Claude, on the account's live Claude plan where the platform sells one: its runs count in the plan's monthly and weekly limits, nothing is billed in credits; an own key or a choice of foldrun's models comes first) or `none` (runs are refused until a key is set); `foldrunModels` is `{ offered, refused, providers: [{ name, title, available, reason, tiers }], prices: [{ provider, model, inputPerMTok, outputPerMTok, cacheReadPerMTok, cacheWritePerMTok }], dailyCapUsd, spentTodayUsd }`, the money in what the account pays. PUT `{ source: "foldrun", supply, ifVersion? }` chooses foldrun's models (`supply`: anthropic, openai, gemini, deepseek or moonshot; a provider the platform cannot serve now, or an account refused them, is a 409; a stale `ifVersion` is a 409); `{ source: "own" }` goes back to the account's own key; a key alone never changes the choice; audited as model.source_set. PUT `{ provider, apiKey, baseUrl?, format? }` (needs `secrets:write`, as does the choice): `provider` is a preset name (anthropic, openrouter, openai, groq, … — see providers) or `custom` with an https `baseUrl` and a `format` (anthropic or openai); a Claude login token (sk-ant-oat…) is refused for any account not allowed the platform's credential. Stored as the account secrets `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY`, `FOLDRUN_MODEL_BASE_URL`, `FOLDRUN_MODEL_FORMAT`. DELETE removes them (the choice stays). Honours Idempotency-Key on PUT; audited as model.key_set / model.key_removed |
|
|
406
|
+
| `/api/account/providers` | GET, POST | GET: the model providers this account's files actually use — each one's preset name, where it is declared, the model a check would send — plus the last daily health check. POST forces one now, which spends one minimal request at each distinct endpoint, and needs the permission that runs and every project. A member or key scoped to some projects sees the account's provider blocks and its own projects' only, in `configured` and in the last check |
|
|
407
|
+
| `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some projects sees those projects, and totals over them; `ledger` is the account's `balanceUsd` and `chargedUsd` (all time), and `waived` the legs the account is not charged for — both `null` to a caller scoped to some projects, since they are the whole account's money. Since API version `2026-10-26` nothing else; earlier pins see `providerCostUsd` and `marginUsd` as `null`. `?from=YYYY-MM-DD&to=YYYY-MM-DD` (UTC days; default the month so far; at most a year; anything else is a 400) bound four blocks, which answer every call (7 Nov 2026): `period` (`from`, `to`); `credits`, `{ pots: { planUsd, boughtUsd }, plan, boughtOldestExpiresAt, unit, usdPerCredit }` — the two credit pots (plan credits pay for compute, storage and network, never for tokens on foldrun's models; bought credits pay for anything) and the plan's terms with `status` and `resetsAt`; `tokens`, `{ totals: { calls, billedCredits, byokTokens }, byModel }`, one row per provider and model with `supply` (`foldrun`, `operator` or `own`), `calls`, `inputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens` and `billedCredits` — a model on the account's own key is listed at `0` with a `billedNote`; and `compute`, `{ meters, planFee, bySize }`, each meter (`vcpu`, `ram`, `disk`, `storage`, `network`, `search`, `browser`, `warm`) with `quantity`, `unit`, `rateCreditsPerUnit` and `credits` — `storage` also `includedGb`, `overGb` (only these are charged) and `basis`, and the three pod meters (the account's search and browser pods and its deploy-time runtime builds, charged for the vCPU and GiB they hold while they live and the bytes they move) `sessions`, `networkGb` and a `note`; `credits` on a pod meter and on `storage` is what the ledger charged over the period —, `planFee` the plan's fee as its own line, `bySize` the step sizes with their `creditsPerHour`; `billed` is what the ledger charged over the period (`totalCredits`, `waived`). They are consumption priced at today's rates, which can differ from `billed` after a price change. `credits`, `planFee` and `billed` are `null` to a caller scoped to some projects, whose `tokens` and `compute` cover those projects, and `null` where nothing is billed. The totals and `workspaces` above are over every retained run, whatever the period |
|
|
408
|
+
| `/api/usage/rates` | GET | the rates this account is charged now (7 Nov 2026): `rates`, `{ creditUsd, vcpuUsdPerHour, ramUsdPerGibHour, diskUsdPerGibMonth, storageUsdPerGbMonth, networkUsdPerGb, margin }` in dollars, `null` where nothing is billed; `plan`, the account's plan terms (`null` to a caller scoped to some projects); and `catalogue`, the same document as `/api/pricing`. The Usage page's Rates tab and `foldrun usage rates` |
|
|
409
|
+
| `/api/approvals` | GET | every gate waiting on a person, across projects — one entry per waiting **step** (`workspace`, `runId`, `flow`, `step`, `agent`, `question`, `asked`, `waitingSince`), oldest first. By step status, not run status: a decided gate leaves the list at once, before the worker resumes the run. `wait: event` steps are not listed; no button answers them. Beside it, `questions`: every question an agent is asking mid-step in a running run (`kind: "question"`, `id`, `workspace`, `runId`, `flow`, `agent`, `question`, `options?`, `askedAt`) — answered with `…/runs/<id>/answer` |
|
|
410
|
+
| `/api/observe?days=` | GET | the account Observe page's analysis, the same function the page renders from: `{ days, timezone, window: { from, to }, previous: { from, to, runs }, kpis, causes, desks, agents, tools, daily }`. `kpis` is the window against the one of the same length before it — `{ runs, finished, succeeded, rate, prevRate, failed, platformFailures, deskFailures, spendUsd, prevSpendUsd, medianSecs }` (`rate` is completed ÷ (completed + failed), `null` with none finished; money is what was charged); `causes` why runs went wrong, the platform's first — `{ kind (platform, verify, timeout, error, blocked, bad, stopped), key, label, platform, count, desks, sample, newest }`; `desks` every project worst first — `{ workspace, runs, rate, prevRate, deskFailures, platformFailures, spendUsd, medianSecs, worst: { what, count }, lastBad }`; `agents` the agents to watch (most failures, then retries, then charged; 10 at most) — `{ workspace, agent, steps, failed, retried, costUsd, chargedUsd, seconds }`; `tools` merged across projects — `{ name, calls, errors, workspaces, p95ms }`; `daily` one bucket per day in `timezone`, a week at least — `{ day, good, attention, failed, platform, other, spendUsd }`. A run it names (`newest`, `lastBad`) is `{ workspace, id, what, outcome, startedAt, finishedAt, failure }`. `days` 1–365, 7 unasked (the page's default). A key scoped to some projects sees theirs |
|
|
411
|
+
| `/api/insights?days=&workspace=` | GET | recurring problems found in the runs of the window (see [Runs](runs#insights)): `{ days, insights: [{ id, kind, workspace, agent, tool?, title, why, fix, credits, steps, evidence: [{ workspace, runId, step }] }] }`. `kind` is `cache` (an agent's big prompt mostly uncached), `big-result` (a tool result over 20k characters sent again on every later model call), `retry-loop` (a tool erroring three or more times in a step) or `timeout` (steps using 80% or more of their `timeout:`); `credits` is about what it cost in the window, null when it is not money. `days` 1–30, 7 unasked. A key scoped to some projects sees theirs |
|
|
412
|
+
| `/api/issues?status=&workspace=` | GET | the account's issues: what went wrong, grouped and kept open until a person resolves it (see [Runs](runs#issues)). One issue is one desk's flow failing at one agent, or ending BLOCKED or BAD, or one platform cause across desks. Each carries `id`, `kind` (`platform`, `failed`, `blocked`, `bad`, `missed` — a scheduled fire that started no run), `status` (`open`, `acknowledged`, `snoozed`, `resolved`), `regressed` and `sinceRevision` (it was resolved and came back, since the revision its new run ran), `snoozedFor`, `workspace`/`workspaces`, `what`, `agent`, `reason`, `action` (what to do), `firstSeen`, `lastSeen`, `count`, the newest `runs`, `recoveredAt` (the flow's newest good run since — it closes nothing), `acknowledged`, `snoozedUntil`, `resolved` and the `history` of what people did. `status` is `active` unasked (open + acknowledged), or `open`, `acknowledged`, `snoozed`, `resolved`, `all`; `workspace` keeps the ones that hit it. A key scoped to some projects sees the issues of those |
|
|
413
|
+
| `/api/issues/<id>` | GET POST | one issue; POST acts on it: `{ action: "acknowledge" | "snooze" | "resolve" | "reopen", for?: "30m" | "4h" | "1d" | "1w", until?: ISO, times?: n, note? }` (editor or above), kept in its history with who did it, and answers `{ issue }` as it now stands. A snooze needs `for`, a future `until`, or `times` (until it happens that many more times; with a time too, whichever comes first). A platform issue is the account's: closing it needs access to every project. A run that goes wrong the same way after a resolve opens the issue again |
|
|
414
|
+
| `/api/account/export` | GET | the owner's copy of what the platform holds about the account, as one JSON file (`foldrun-<account>-export.json`): `workspaces` (with their flows), `members` (email, role, scope, since), `runs` (an index — id, project, flow, status, times, headline) and the whole `ledger` (each line's charge and what it was for; the platform's provider cost, its internal dedup `key` and `pricingVersion` are left out). `billing:manage`, so the owner; audited as `account.exported`. The markdown itself comes from `foldrun pull` or the source API |
|
|
415
415
|
| `/api/account/telemetry/test` | POST | send one made-up run as an OpenTelemetry trace to the collector `telemetry:` names — the account's, or `{ workspace }`'s — with its header secrets filled from the vault; `{ ok, status?, error?, spans?, endpoint }`. `409` when no `telemetry:` is set. Needs `workspace:manage` |
|
|
416
|
-
| `/api/account/jobs?workspace=` | GET | the four jobs (governance, guardrail, observability, evaluation) and each `AGENTS.md` field of each: `{ jobs: [{ name, title, what, fields: [{ key, account, workspace?, combine, writable }] }] }` — the account's value and the
|
|
417
|
-
| `/api/account/pause` | GET, POST, DELETE | the account's kill switch: the same as a
|
|
416
|
+
| `/api/account/jobs?workspace=` | GET | the four jobs (governance, guardrail, observability, evaluation) and each `AGENTS.md` field of each: `{ jobs: [{ name, title, what, fields: [{ key, account, workspace?, combine, writable }] }] }` — the account's value and the project's when `workspace` is given (null: unset), as written with blocks folded — to a caller scoped to some projects the account's `notify` and `telemetry` are `{ hidden: true, … }` (set; no URL, headers or token); `combine` is how the two meet at run time (`workspace replaces`, `either turns it on`, `both apply`, `per key`, `per field`, `level nearest, sites from both`, `account only`); `writable` is whether that scope's settings PATCH (`/api/account`, or the project's) writes it — the rest are written in `AGENTS.md`. See [The four jobs](four-jobs) |
|
|
417
|
+
| `/api/account/pause` | GET, POST, DELETE | the account's kill switch: the same as a project's `/pause`, for every project at once. GET `{ paused, account, workspaces }` (`workspaces`: those paused on their own). POST `{ reason?, stop?: true }`, DELETE resumes the account — a project paused on its own stays paused. Needs `workspace:manage` and access to every project |
|
|
418
418
|
| `/api/account/close` | POST | the owner asks to close the account — in person, never a key, with `confirm` set to the account's name and an optional `reason`. Not a delete: the account is suspended at once (runs in flight finish, sign-in and the export still work), `closeRequested` is set on its admin state, and the platform's operator is mailed to settle the last invoice and any refund. A plan's subscription is set to stop at the end of the period already paid for — nothing renews, no refund — and `billing` says what was done (the close stands even if Stripe could not be reached; `billing` then says so). Returns `{ ok, suspended, notified, billing }`; 409 when already asked. Hosted installs only |
|
|
419
419
|
| `/api/account/backups` | GET | what is backed up for this account: `policy` (`schedule`, `keepLocal`, `keepOffsiteDays`, `encrypted`, `covers`, `excludes`), `last`, `backups` (each nightly archive that holds this account, newest first: `id`, `at`, `bytes`, `files`, `runs` (always null: they measured the whole archive, which holds every account on the server, so they are not shown to one — 30 Oct 2026), `sha256` (the archive inside the encryption — what a decrypt must reproduce), `kinds` — files, database, keys — `verified`, `offsite`, `keepDays`, `encrypted` (sealed with age before it left the server; false for archives taken before October 2026), `recipient` (the key's fingerprint, `sha256:<16 hex>`, or null)), `requests` (earlier restore requests) and `workspaces` (`name`, `head`, `history`, `lastChange`) — what a restore can reach. See [Backups and restore](backups-and-restore.md) |
|
|
420
|
-
| `/api/account/backups/requests` | GET, POST | ask the platform team to restore what an account cannot restore itself. POST `{ what, target, workspace?, backupId?, note? }` (`what` is runs, state, storage or everything) records the request, mails the operator and audits it as `backup.restore_requested`; answers 201 `{ ok, request }` with `notified` saying whether the mail went. Restores nothing. `workspace:manage`, and a member scoped to some
|
|
421
|
-
| `/api/account/api` | GET, PATCH | how this account meets the API — GET `{ version: { current, pinned, effective, supported, supportMonths }, limits: { plan, windowSeconds, perCredential: { read, write }, perAccount: { read, write } }, usage }`. `usage` is the last 30 days — `{ days, versions: [{ version, requests, lastSeen }], deprecated: [{ route, requests, lastSeen, deprecatedAt, sunsetAt, link, callers: [{ credential, requests, lastSeen }] }] }`, `credential` naming a key by its label and prefix — or `null` when it could not be read. A caller scoped to some
|
|
422
|
-
| `/api/account/beta` | GET PUT | the account's beta: `GET` → `{ beta, flags: [{ name, description, on, source }] }` (the beta flags as they stand for it); `PUT { beta: true \| false }` joins or leaves it (an admin of every
|
|
420
|
+
| `/api/account/backups/requests` | GET, POST | ask the platform team to restore what an account cannot restore itself. POST `{ what, target, workspace?, backupId?, note? }` (`what` is runs, state, storage or everything) records the request, mails the operator and audits it as `backup.restore_requested`; answers 201 `{ ok, request }` with `notified` saying whether the mail went. Restores nothing. `workspace:manage`, and a member scoped to some projects must name one. GET lists this account's requests |
|
|
421
|
+
| `/api/account/api` | GET, PATCH | how this account meets the API — GET `{ version: { current, pinned, effective, supported, supportMonths }, limits: { plan, windowSeconds, perCredential: { read, write }, perAccount: { read, write } }, usage }`. `usage` is the last 30 days — `{ days, versions: [{ version, requests, lastSeen }], deprecated: [{ route, requests, lastSeen, deprecatedAt, sunsetAt, link, callers: [{ credential, requests, lastSeen }] }] }`, `credential` naming a key by its label and prefix — or `null` when it could not be read. A caller scoped to some projects gets `usage: null` and `usageHidden: true`: who calls which route is the whole account's; PATCH `{ version: "YYYY-MM-DD" \| null }` pins the version API-key requests without a `Foldrun-Version` header get (null: always current); the dashboard always gets current. `keys:manage`; PATCH also needs every project (403 to a member or key scoped to some), since the pin is every key's. See [api-usage](api-usage.md) |
|
|
422
|
+
| `/api/account/beta` | GET PUT | the account's beta: `GET` → `{ beta, flags: [{ name, description, on, source }] }` (the beta flags as they stand for it); `PUT { beta: true \| false }` joins or leaves it (an admin of every project; `403` for a key or person given only some) and answers the same plus `changed`. Audited as `account.beta_joined` / `account.beta_left`. See [Beta features](feature-flags#beta-features) |
|
|
423
423
|
| `/api/account/flags` | GET | the feature flags as they stand for this account — `{ flags: [{ name, description, owner, default, beta, on, source, rollout }] }`, `source` being what decided it: `account` (an override for this account), `global` (the install-wide setting), `beta` (a flag marked beta, the account being in the beta), `rollout` (a percentage of accounts, by a stable hash of account and flag; `rollout` is the percentage) or `default`. Read-only, every role; only the platform's operator changes a flag (a self-hosted install runs every flag at its default). See [Feature flags](feature-flags.md) |
|
|
424
424
|
| `/api/openapi.json` | GET | this API as an OpenAPI 3.1 document — every route and method, bearer auth, the rate-limit, version and Idempotency-Key headers, and request/response schemas for runs, flow runs, deploy, source, secrets, keys and billing. No key needed. Generated from the route files by `scripts/gen-openapi.mjs`; the dashboard renders it at Docs → API reference, `foldrun api spec` saves it |
|
|
425
|
-
| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB, diskGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory, disk }`, merged over what is set: a figure not sent is kept, `null` drops one, `compute: null` drops all), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place. To a caller scoped to some
|
|
426
|
-
| `/api/customers` | GET, PATCH | your own users' limits and block list ([end customers](runs#end-customers)): GET `{ limits: { startsPerMinute, maxOpenRuns, gatewayRpm, gatewayConcurrency, dailyModelUsd }, defaults, blocked: [{ customer, by, reason, at }] }` — anyone in the account; PATCH changes the limits (whole numbers 1–100,000; `dailyModelUsd` dollars a day, kept to the cent; `null` puts one back to the default) — an admin over every
|
|
425
|
+
| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB, diskGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory, disk }`, merged over what is set: a figure not sent is kept, `null` drops one, `compute: null` drops all), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place. To a caller scoped to some projects GET says these are set, never where they go: `notify` loses its `url` and carries `hidden: true` when one is set, and `telemetry` is `{ endpoint: "", headers: {}, hidden: true }`. PATCH needs every project |
|
|
426
|
+
| `/api/customers` | GET, PATCH | your own users' limits and block list ([end customers](runs#end-customers)): GET `{ limits: { startsPerMinute, maxOpenRuns, gatewayRpm, gatewayConcurrency, dailyModelUsd }, defaults, blocked: [{ customer, by, reason, at }] }` — anyone in the account; PATCH changes the limits (whole numbers 1–100,000; `dailyModelUsd` dollars a day, kept to the cent; `null` puts one back to the default) — an admin over every project (`403` otherwise), audited as `customer.limits` |
|
|
427
427
|
| `/api/customers/usage?days=` | GET | what each end customer's calls on foldrun's models were charged over the last `days` UTC days (1–90, default 7): `{ days, customers: [{ customer, chargedUsd, todayUsd, calls }] }`, newest-spending first, at most 500, open estimates included — anyone in the account |
|
|
428
|
-
| `/api/customers/<customer>/block` | PUT, DELETE | block one end customer (`{ reason? }`) — its runs are refused at start and stop at their next model call — or unblock it (`404` when it was not blocked). An admin over every
|
|
429
|
-
| `/api/account/agents-md` | GET, PUT | the account's own `AGENTS.md`, whole — the shared context and defaults every agent in every
|
|
430
|
-
| `/api/audit?since&until&action&actor&workspace&limit&cursor&format` | GET | the account's audit log, newest first — the caller's account only, whatever a header, query or body names. The owner and unscoped admins (people, or `admin` keys); `audit:read`, and refused to a member or key scoped to some
|
|
431
|
-
| `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a
|
|
432
|
-
| `/api/search?q=` | GET | find anything in the account by name —
|
|
433
|
-
| `/api/schedule` | GET, POST | GET: every scheduled flow with `valid` (the cron parses) and `upcoming` (the next three fires). POST: tick the scheduler now for this account alone — its due cron, `once:` and watch flows go now (they were due anyway); `workspace:manage` over every
|
|
428
|
+
| `/api/customers/<customer>/block` | PUT, DELETE | block one end customer (`{ reason? }`) — its runs are refused at start and stop at their next model call — or unblock it (`404` when it was not blocked). An admin over every project; audited as `customer.blocked` / `customer.unblocked` |
|
|
429
|
+
| `/api/account/agents-md` | GET, PUT | the account's own `AGENTS.md`, whole — the shared context and defaults every agent in every project reads, above its project's AGENTS.md. GET answers `{ content, sha256, exists }`. PUT `{ content, ifMatch?, message? }` writes it whole and answers `{ ok, sha256, issues }` (`unchanged: true` when it already said that). Checked as a deploy checks AGENTS.md: a problem a deploy would refuse is `422` with the `issues` and nothing written; warnings come back with the write. `ifMatch` — the `sha256` a GET answered, or `null` for "there was no file" — makes it a `409` if the file changed since. At most 256 KB. Account-wide callers only, both ways (a member or key scoped to some projects is `403`: the file can name notify and telemetry targets for every project); PUT needs `workspace:manage` (an admin). `foldrun deploy` at an account root sends it and `foldrun pull` fetches it; Settings → Policies → AGENTS.md edits it. Audited as `account.agents_md_set`. Idempotent |
|
|
430
|
+
| `/api/audit?since&until&action&actor&workspace&limit&cursor&format` | GET | the account's audit log, newest first — the caller's account only, whatever a header, query or body names. The owner and unscoped admins (people, or `admin` keys); `audit:read`, and refused to a member or key scoped to some projects, because the log is the whole account's. `since`/`until`: `7d`, `24h`, `30m` or a date; `action`: exact (`apikey.created`) or a family (`apikey`); `actor`: exact (an email, `key:<label>`, `support:<email>`); `workspace`: entries about one; `limit` 1–1000 (100; 1000 for CSV); `cursor`: the `next` of the page before. JSON `{ entries: [{ id, at, actor, action, subject, detail }], next, retention }`; `format=csv` downloads the same rows (`x-next-cursor` header when there are more). Records sign-ins and refusals, sign-outs, session revokes, password and email changes, MFA on/off, key mint/rotate/revoke, invites, joins, role/scope changes, removals, ownership transfers, secrets set/deleted (by name — never a value), deploys, project deletes, plan and billing changes, export and close requests, and `support.viewed`/`support.ended`. The platform operator's own levers (`operator.*`) are the platform's record and not listed. Kept 365 days (`audit.retention_days`; an install without a database keeps its file-backed log), and no longer than the account |
|
|
431
|
+
| `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a project's or the account's. GET needs a signed-in tenant — a project's picture, a caller who may open that project (403 otherwise) — and is privately cached for a year — the URL's `?v=` changes with the picture |
|
|
432
|
+
| `/api/search?q=` | GET | find anything in the account by name — projects, agents, flows, tools, skills, knowledge, memory, runs (by id, flow or headline); ranked, at most six per kind. The dashboard's Find palette reads it |
|
|
433
|
+
| `/api/schedule` | GET, POST | GET: every scheduled flow with `valid` (the cron parses) and `upcoming` (the next three fires). POST: tick the scheduler now for this account alone — its due cron, `once:` and watch flows go now (they were due anyway); `workspace:manage` over every project; returns `{ ok, fired }`. An impossible cron (`0 0 30 2 *`) is `valid` with `upcoming: []` |
|
|
434
434
|
| `/api/library/<kind>?path=` | GET, POST, PUT, DELETE | account-level shared documents (`name`, `content`, `path`, `template`); DELETE `{ path }` removes one file or folder — `.` (the whole shelf) is refused |
|
|
435
435
|
| `/api/library/gallery` | GET, POST | GET: every tool and skill the platform ships to every account, whole (`tools: [{ name, kind, title, description, files: [{ kind, file, content }], installed }]`, `kind` being `tools`, `skills` or `scripts`, `installed` being `current`, `differs` or null for this account's own copy) — what `foldrun gallery` reads and lays down on a laptop. POST: update an installed gallery tool or skill to the version the platform ships (`tool`, its name) — written through the revision log, so the previous copy is one revision back |
|
|
436
436
|
|
|
@@ -441,9 +441,9 @@ least role that may take that action. Reads are open to every role.
|
|
|
441
441
|
|
|
442
442
|
| role | may |
|
|
443
443
|
|---|---|
|
|
444
|
-
| `viewer` | read everything —
|
|
445
|
-
| `editor` | + edit files, upload, deploy (to a
|
|
446
|
-
| `admin` | + create and delete
|
|
444
|
+
| `viewer` | read everything — projects, runs and their output, files, history, usage |
|
|
445
|
+
| `editor` | + edit files, upload, deploy (to a project that exists), push; run, stop, re-run, approve and promote runs; test tools |
|
|
446
|
+
| `admin` | + create and delete projects; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
|
|
447
447
|
| `owner` | + billing; make and unmake admins; transfer the account |
|
|
448
448
|
|
|
449
449
|
There is exactly one owner: the account's creator until they transfer it.
|
|
@@ -461,16 +461,16 @@ person: a key names an account, never a who.
|
|
|
461
461
|
|
|
462
462
|
| Route | Methods | |
|
|
463
463
|
|---|---|---|
|
|
464
|
-
| `/api/billing` | GET, POST | balance and recent ledger entries — to a member or key scoped to some
|
|
464
|
+
| `/api/billing` | GET, POST | balance and recent ledger entries — to a member or key scoped to some projects, only those projects' charges (no other project's runs, no top-ups or refunds); POST answers `404` to every caller — credit comes through checkout (`/api/billing/checkout`) or an adjustment by the platform's operator |
|
|
465
465
|
| `/api/billing/checkout` | POST | a Stripe session (`usd`) |
|
|
466
466
|
| `/api/billing/confirm?session_id=` | GET | settle one |
|
|
467
467
|
| `/api/billing/card` | POST | save a card |
|
|
468
|
-
| `/api/billing/details` | GET, PUT | who the invoices are made out to — GET `{ details, stripe, customer, tax }` for anyone who can see billing and every
|
|
468
|
+
| `/api/billing/details` | GET, PUT | who the invoices are made out to — GET `{ details, stripe, customer, tax }` for anyone who can see billing and every project (403 to a member or key scoped to some, as for the statement); PUT (the owner) `legalName` (required), `email`, `abn` (checked against the ABN rule), `address` `{ line1, line2, city, state, postcode, country }` (two-letter country) or `null`. Every problem comes back at once as `errors` with a `400`. Kept first, then sent to the Stripe customer (name, address, the ABN as its `au_abn` tax id): answers `synced`, and `syncError` with Stripe's words when Stripe refused — the details stand either way |
|
|
469
469
|
| `/api/billing/portal` | POST | a Stripe Billing Portal session for the account's customer (the owner): answers `url`. Optional `returnTo`, a `/dashboard/…` path to come back to. `501` without Stripe |
|
|
470
|
-
| `/api/billing/invoices` | GET | the Invoices tab as data (hosted only; 5 Nov 2026): `invoices` is the plan's tax invoices from Stripe, newest first — `{ id, number, description, createdAt, amount, currency, status, url, pdfUrl }`, `amount` in the invoice's currency and `url` Stripe's hosted page; `receipts` is every credit purchase on the ledger, newest first — `{ t, usd, label, receiptUrl }`, `receiptUrl` Stripe's hosted receipt or `null` for a credit not paid by card; `stripe` is false when Stripe is not configured or the account has no customer there (no invoices then). The whole account's payments, so refused (403) to a member or key scoped to some
|
|
471
|
-
| `/api/billing/statement?month=&format=` | GET | one month of the ledger as a statement. JSON by default; `format=csv` downloads it with the month, the account and the spent and added totals in its header. `month` is `YYYY-MM`, default the current month. What the customer sees is the charge; the platform's provider cost is not on it. The whole account's money, so refused (403) to a member or key scoped to some
|
|
470
|
+
| `/api/billing/invoices` | GET | the Invoices tab as data (hosted only; 5 Nov 2026): `invoices` is the plan's tax invoices from Stripe, newest first — `{ id, number, description, createdAt, amount, currency, status, url, pdfUrl }`, `amount` in the invoice's currency and `url` Stripe's hosted page; `receipts` is every credit purchase on the ledger, newest first — `{ t, usd, label, receiptUrl }`, `receiptUrl` Stripe's hosted receipt or `null` for a credit not paid by card; `stripe` is false when Stripe is not configured or the account has no customer there (no invoices then). The whole account's payments, so refused (403) to a member or key scoped to some projects, as the statement is |
|
|
471
|
+
| `/api/billing/statement?month=&format=` | GET | one month of the ledger as a statement. JSON by default; `format=csv` downloads it with the month, the account and the spent and added totals in its header. `month` is `YYYY-MM`, default the current month. What the customer sees is the charge; the platform's provider cost is not on it. The whole account's money, so refused (403) to a member or key scoped to some projects, as the audit log is |
|
|
472
472
|
| `/api/billing/wallet` | GET, PUT | the balance summary (burn, runway, daily spend, month to date, the suggested top-up), the refill rule and the low-balance email — GET `{ enabled, stripe, summary, cardSaved, autoTopUp, email, dunning, tomanTopUp }`, PUT `autoTopUp`, `email`. `dunning.status` is `none`, `grace` (a plan invoice failed; runs go on until `graceUntil`) or `suspended` (new runs paused until it is paid), with `payUrl`, `amountDue` (minor units) and `currency`. `tomanTopUp` is `{ url }` — foldrun.ir's charge page with this account filled in — or null where foldrun.ir cannot sell now |
|
|
473
|
-
| `/api/billing/plans` | GET | the catalogue (four plans — Free, Starter, Pro and Scale: fee, credits, per-credit price, storage, compute at once,
|
|
473
|
+
| `/api/billing/plans` | GET | the catalogue (four plans — Free, Starter, Pro and Scale: fee, credits, per-credit price, storage, compute at once, projects, lane, and whether unused credits roll over), where this account stands (plan, status, this cycle's credits and what is left, when it resets), the balance in dollars and credits, and any overdraft the platform has allowed |
|
|
474
474
|
| `/api/billing/subscribe` | POST, DELETE | POST `plan` — starter, pro or scale (Free is granted, not bought). With no subscription yet, answers `url`: a Stripe Checkout in subscription mode; the return trip starts the first cycle. With a live one, changes it at Stripe at once, prorated (an upgrade is invoiced today and the bigger bundle lands with it; a downgrade comes back as credit on the next invoice), and answers `changed: true` — only once its prorated invoice is paid: when the payment needs the customer (a declined card, 3-D Secure) the change waits at Stripe as a pending update, nothing about the plan moves, and the answer is 402 `{ pending: true, payUrl }` — paying that invoice applies it; unpaid, Stripe drops it and voids the invoice after 23 hours. A plan set to stop and changed this way stays set to stop once paid — resuming it is the customer's own choice (`resume: true`); nothing resumes on its own. A plan set to stop at the period's end is still that live subscription: choosing a plan takes the stop off (and changes it if it is another plan) — never a second Checkout. With no subscription known here but one still billing at Stripe for the account's customer, 409: a second is not started. POST `resume: true` takes a pending cancellation off — nothing is charged and no cycle moves. DELETE ends the plan with the current cycle: the credits stand until then, and credits bought on top are kept |
|
|
475
475
|
| `/api/billing/stripe` | POST | Stripe's webhook — signature-verified, not for you. Every delivery is logged. Beside top-ups it turns plan cycles: one grant per (subscription, plan, period), whichever of the checkout, `invoice.paid` (either invoice shape) or `customer.subscription.updated` arrives first; `invoice.payment_failed` marks the plan past due and starts dunning (an email, a grace period, then new runs paused — see budgets-and-billing.md), `invoice.paid` and `invoice.voided` end it, `customer.subscription.deleted` ends the plan that subscription paid for — what is left of the bundle expires, the levers come off, money the customer added stays. `charge.refunded` debits a refunded top-up (never a plan fee), `charge.dispute.created` debits a chargeback and `charge.dispute.closed` returns it when won. Answers 500 — so Stripe redelivers — only when a lookup the event needs failed. The full event list is in budgets-and-billing.md |
|
|
476
476
|
| `/api/billing/partner/topups/rate` | GET | foldrun.ir only, HMAC-signed (see [Paying in Toman](budgets-and-billing#paying-in-toman-foldrunir)) — the Toman rate it sells at: `{ tomanPerUsd, setAt, min, max }`; `503` while no rate is set or it has gone stale |
|
|
@@ -540,11 +540,11 @@ signed-in person, never by a key — mints an ordinary API key at their role.
|
|
|
540
540
|
| `/api/cli/login/<id>` | GET | `{ status }` — `pending`, `denied`, `expired`, or `approved` with `token`, `account`, `email`, `role`. The key is returned once; the request is gone after |
|
|
541
541
|
| `/api/cli/authorize` | GET, POST | `?code=` describes the request: machine, expiry, `createdAt`, `requestedFrom` (the asking network as an IPv4 /24 or IPv6 /48, from the trusted proxy — null when not known), `requestedCountry` (behind Cloudflare; else null), `sameNetwork` (whether the browser looking is on that network; null when either is not known) and `approveBy`. POST `{ code, decision }` from a session approves (mints the key, labelled `cli · <hostname>`, ending in 90 days — the CLI renews it itself before then, see `/api/keys/<id>/rotate`) or denies — `decision` is `approve` or `deny`, and absent approves; any other word is a `400`. A request more than five minutes old can no longer be approved (`410`; it can still be denied) — device-code phishing, RFC 8628 §5.4. Every role may sign its own CLI in; an owner's key is an admin's |
|
|
542
542
|
| `/api/me` | GET | who is calling: `account`, `owner`, `role`, `workspaces` (null: all), and the `actor` — a person's email, or a key's id, label, prefix, who minted it, `expiresAt` (null: never) and `origin` (`cli-login` for a key `foldrun login` minted, else null); `person` — `{ email, firstName, lastName, timezone }` for a signed-in session or a `foldrun login` key, null for any other key |
|
|
543
|
-
| `/api/me/onboarding` | GET, PATCH | the account's getting-started steps, each derived from what is really there — `{ steps: [{ id, title, why, href, cli?, done, hidden }], done, total, complete, next, upNext, hidden, dismissed, dismissedAt, welcomedAt }`. Steps: `model` (first; only for an account that must bring its own key — done once it has one, or a `provider:` block in the account's AGENTS.md), `workspace`, `agent` (an agent written or deployed after the
|
|
544
|
-
| `/api/me/inbox` | GET, POST | your inbox — what waits on you across the
|
|
545
|
-
| `/api/me/notifications` | GET, PATCH | what mail you get. GET `{ email, categories: [{ category, label, description, required, why?, perWorkspace, enabled, workspaces: { <ws>: bool } }] }` for `security`, `invites`, `billing`, `account` (required — always sent) and `run-alerts`, `approvals` (per
|
|
543
|
+
| `/api/me/onboarding` | GET, PATCH | the account's getting-started steps, each derived from what is really there — `{ steps: [{ id, title, why, href, cli?, done, hidden }], done, total, complete, next, upNext, hidden, dismissed, dismissedAt, welcomedAt }`. Steps: `model` (first; only for an account that must bring its own key — done once it has one, or a `provider:` block in the account's AGENTS.md), `workspace`, `agent` (an agent written or deployed after the project was made), `run`, `success` (a completed run), `secret`, `trigger` (a schedule or webhook), `teammate` (a second member), `billing` (hosted, not fully waived: a saved card or a plan), `cli` (any API key or CLI login). `next` is the first step not done; `upNext` the first neither done nor hidden by this person; `hidden` the step ids they hid; `welcomedAt` when they first opened the welcome flow (`/dashboard/welcome`; the home page sends a person there once, the first time they open an account with no project). `?workspace=<name>` adds `checklist: { workspace, items: [{ id, title, why, href, done, hidden }], done, total, complete, dismissed, show }` — that project's checklist: `run` (a flow that ran to the end), `trigger` (a schedule or webhook), `owner` (`owner:` by the cascade), `eval`, `notify` (`notify:` with an address or URL, the project's or the account's); a project outside the caller's scope, or none, is a `404`. A caller scoped to some projects is answered over those projects alone — no other project's name is in a step's `href`. PATCH, for the signed-in person (kept in their prefs), any of: `{ dismissed: true or false }` hides or brings back the dashboard card; `welcomed: true` records the welcome flow as seen; `hide: [step ids]`, `show: [step ids]` hide or bring back single steps; `checklist: { workspace, dismissed?, hide?: [item ids], show?: [item ids] }` the same for a project's checklist. An unknown id is a `400`. A key reads nothing hidden and `dismissed: false`, and cannot PATCH |
|
|
544
|
+
| `/api/me/inbox` | GET, POST | your inbox — what waits on you across the projects you may see. GET `{ person, items: [{ id, kind (approval, question, issue, proposal, run), bucket (mine, started, team), why, workspace, title, detail, at, href, read, dismissed }], counts: { mine, started, team, unread } }`, newest first. `mine` is assigned to you (named in `approvers:`, owner of the flow or agent, or you asked for the proposal); `started` is runs you started — failed or BLOCKED/BAD this week, a gate on one (someone else decides it), a question it asked; `team` is the rest that waits in your projects. By default `mine` and `started`; `?bucket=mine\|started\|team\|all`, `?kind=`, `?workspace=`, `?dismissed=1` for what you set aside. `counts.unread` is unread `mine` + `started`. POST `{ ids \| id, action: read\|unread\|dismiss\|restore }` changes your view only — dismissing never decides a gate or resolves an issue; ids name an occurrence, so a thing that happens again is new. A key acts for the person who minted it, inside the key's own scope; one no person minted is a `400` |
|
|
545
|
+
| `/api/me/notifications` | GET, PATCH | what mail you get. GET `{ email, categories: [{ category, label, description, required, why?, perWorkspace, enabled, workspaces: { <ws>: bool } }] }` for `security`, `invites`, `billing`, `account` (required — always sent) and `run-alerts`, `approvals` (per project), `low-balance`, `product-updates`. PATCH `{ category, enabled, workspace? }` or `{ preferences: [ … ] }`; answers the same as GET. Turning a required category off is a `409` with the reason; `workspace` on an account-wide category is a `400`; `enabled: true` account-wide clears that category's per-workspace offs. A key acts for the person who minted it |
|
|
546
546
|
| `/api/me/preferences` | GET, PATCH | your own display preferences: `{ theme, runViews }` — `theme` is `system` (the default: follow the computer's light or dark setting), `light` or `dark`; `runViews` your saved run searches, `[{ name, query }]` (see [Runs](runs#searching-runs)). PATCH `{ theme }` and/or `{ runViews }` (the whole list, at most 20, each query of the runs filters) answers the same; anything else is a `400`. Kept in your prefs, so it follows you to every browser; the dashboard applies it on the server, before the first paint. A key acts for the person who minted it; a key minted by nobody is a `400` |
|
|
547
|
-
| `/api/unsubscribe?token=` | POST | one-click unsubscribe (RFC 8058) — no login, the signed token is the credential. It is the `List-Unsubscribe` URL on every optional mail, beside `List-Unsubscribe-Post: List-Unsubscribe=One-Click`; a mail client POSTs `List-Unsubscribe=One-Click` to it. Turns off the one category (for the one
|
|
547
|
+
| `/api/unsubscribe?token=` | POST | one-click unsubscribe (RFC 8058) — no login, the signed token is the credential. It is the `List-Unsubscribe` URL on every optional mail, beside `List-Unsubscribe-Post: List-Unsubscribe=One-Click`; a mail client POSTs `List-Unsubscribe=One-Click` to it. Turns off the one category (for the one project) the token was minted for, for its address. The token may also come as a form field (`token`, and `from=page` to be sent back 303 to the `/unsubscribe` confirmation page) or JSON. `200 { ok, category, workspace }`; `400` no token, `401` forged, `410` expired (180 days; `FOLDRUN_UNSUBSCRIBE_TTL_DAYS`). Never on a GET — `/unsubscribe?token=` is the page that asks first |
|
|
548
548
|
|
|
549
549
|
## OAuth — connecting an agent to a third party
|
|
550
550
|
|
|
@@ -596,7 +596,7 @@ Desktop, Cursor, Codex and any other MCP client. An **API key**
|
|
|
596
596
|
(`Authorization: Bearer fr_api_…`) or an AI app's **OAuth access token** (below)
|
|
597
597
|
opens it — never a session cookie, never an A2A key — and every tool is a call
|
|
598
598
|
to one of the routes above, made with that credential, so it answers what the
|
|
599
|
-
route would: its role, its
|
|
599
|
+
route would: its role, its projects and every refusal hold. MCP's Streamable HTTP transport, stateless: one JSON-RPC 2.0
|
|
600
600
|
message per request, answered as JSON — no SSE stream, no session id, no
|
|
601
601
|
batches. Errors before a message is read (no key, a refused key, a foreign
|
|
602
602
|
`Origin`, an `MCP-Protocol-Version` it does not speak) are JSON-RPC error
|
|
@@ -610,7 +610,7 @@ with `HTTP <status>: <the route's error>`.
|
|
|
610
610
|
| `/api/mcp/oauth/authorize` | GET, POST | the person's half of the sign-in, for the page at `/mcp/authorize` — a signed-in person only, never a key or a support view. GET `?request=<the app's query>` checks it and answers `{ client: { name, id, kind, uri }, redirectHost, loopback, scopes, account, person: { email, role }, workspaces, allWorkspaces }`; POST `{ request, decision: approve\|deny, access?: read\|write, workspaces?: [names] \| null }` answers `{ ok, redirect }` — the app's redirect URI with a one-time `code` (ten minutes), `state` and `iss`, or with `error=access_denied`. A request that names an unknown app or a redirect URI it did not register is `400` and never redirected; the rest of its faults (no PKCE `S256` challenge, a `resource` that is not this `/api/mcp`, an unknown scope) come back as `{ redirect }` with OAuth's error. `access: write` needs the app to have asked for `mcp:write`; `workspaces` must be ones the person may open (`403` otherwise) |
|
|
611
611
|
| `/api/mcp/oauth/token` | POST | OAuth 2.1's token endpoint, form-encoded (JSON is read too), no key: `grant_type=authorization_code` with `code`, `redirect_uri`, `code_verifier` (PKCE S256) and `client_id` — or the app's secret, Basic or in the form —, or `grant_type=refresh_token` with `refresh_token`. `resource`, when sent, must be this `/api/mcp`. Answers `{ access_token, token_type: "Bearer", expires_in: 3600, refresh_token, scope }` with `Cache-Control: no-store`. A code is good once, right or wrong. A refresh token is rotated on use; one used twice revokes the whole connection. Errors: `400 invalid_grant` / `invalid_target` / `unsupported_grant_type`, `401 invalid_client` |
|
|
612
612
|
| `/api/mcp/oauth/revoke` | POST | RFC 7009's revocation endpoint, form-encoded (JSON is read too), no key: `token` (an `fmcp_at_` or `fmcp_rt_` this app holds), optional `token_type_hint` (`access_token`, `refresh_token`), and the app's `client_id` or its secret as at the token endpoint. Either token ends the connection, and every token it issued. `200` with an empty body, also for a token already unknown, expired or revoked (§2.2); `400 unauthorized_client` for another app's token, `401 invalid_client` for a wrong secret. Audited as `mcp.revoked`. Advertised as `revocation_endpoint` |
|
|
613
|
-
| `/api/mcp/clients` | POST | register a machine client for `/api/mcp` (client credentials): `{ name, role?, workspaces?, access?: read\|write, token_auth?: client_secret_basic\|client_secret_post\|private_key_jwt, jwks?, jwks_uri? }` → `201 { client_id, client_secret?, grant, token_endpoint, token_endpoint_auth_method }`. The secret is shown once. Role and
|
|
613
|
+
| `/api/mcp/clients` | POST | register a machine client for `/api/mcp` (client credentials): `{ name, role?, workspaces?, access?: read\|write, token_auth?: client_secret_basic\|client_secret_post\|private_key_jwt, jwks?, jwks_uri? }` → `201 { client_id, client_secret?, grant, token_endpoint, token_endpoint_auth_method }`. The secret is shown once. Role and projects are never above the caller's, and are capped by the registering admin's again at every use. `keys:manage`, and a person (a session, or a key minted by one). It gets access tokens at the token endpoint with `grant_type=client_credentials`, no refresh token. It is listed by `GET /api/mcp/connections` with `machine: true` and ended by `DELETE /api/mcp/connections/<id>`, after which it is `invalid_client`. Audited as `mcp.connected` |
|
|
614
614
|
| `/api/mcp/connections` | GET | the AI apps connected over OAuth: `{ connections: [{ id, client, clientId, redirectHost, person, role, workspaces, access: read\|write, createdAt, lastUsedAt, revokedAt }], everyone }` — every one for `keys:manage` (`everyone: true`), else your own. `?all=1` adds the revoked |
|
|
615
615
|
| `/api/mcp/connections/<id>` | DELETE | disconnect one: the grant is revoked and every token it issued stops at once. Your own, or anyone's with `keys:manage` (`403` otherwise); `404` when there is none or it is already revoked. Audited as `mcp.revoked` |
|
|
616
616
|
|
|
@@ -625,5 +625,5 @@ than taking a pasted key — finds this from the `401` of `/api/mcp`:
|
|
|
625
625
|
are `mcp:read` and `mcp:write`. The access token (`fmcp_at_…`, an hour) opens
|
|
626
626
|
`POST /api/mcp` and nothing else — sent to any other route it is `403` — and
|
|
627
627
|
acts as the person who approved it, at the lower of the role they chose then
|
|
628
|
-
and the one they hold now, in the
|
|
628
|
+
and the one they hold now, in the projects both allow; a read-only
|
|
629
629
|
connection is refused every write.
|