HTTP API reference
Every endpoint, grouped. Use with an API key.
This is a high-level index. Each endpoint accepts standard JSON unless noted. Auth is Authorization: Bearer kf_… for API-key access or session cookie for browser access.
Auth
| Method | Path | Purpose |
|---|
POST | /auth/login | Login with email + password. |
POST | /auth/register | Create account. |
GET | /auth/verify?token=… | Verify email. |
POST | /auth/forgot | Request password reset. |
POST | /auth/reset | Submit new password. |
POST | /auth/logout | Log out current session. |
POST | /api/auth/mfa-setup | Initiate TOTP setup. |
POST | /api/auth/mfa-verify | Confirm TOTP. |
Account
| Method | Path | Purpose |
|---|
GET | /api/account/sessions | List active sessions. |
POST | /api/account/sessions/<sid>/revoke | Revoke a session. |
POST | /api/account/change-password | Change password. |
POST | /api/account/update-profile | Update name/email/avatar. |
POST | /api/account/request-delete | Initiate 30-day deletion. |
POST | /api/account/cancel-delete | Cancel pending deletion. |
GET | /api/account/export-data | Generate full data export. |
GET | /api/account/audit-list | Read audit log. |
GET | /api/account/api-keys | List API keys. |
POST | /api/account/api-keys | Create API key. |
DELETE | /api/account/api-keys/<id> | Revoke API key. |
Project
| Method | Path | Purpose |
|---|
POST | /api/project/load | Open a project. |
POST | /api/project/rescan | Rescan repo + symbols + findings. |
GET | /api/project/tree | File tree (lazy-load on expand). |
GET | /api/project/file?path=… | Read file contents. |
GET | /api/project/symbols?q=… | Symbol lookup. |
GET | /api/project/search?q=… | Full-text search. |
GET | /api/project/recent | Recently opened projects. |
Agent
| Method | Path | Purpose |
|---|
POST | /api/agent/run | Run an agent task (SSE). |
GET | /api/agent/follow?cursor=N | Reattach to an in-flight run. |
POST | /api/agent/cancel/<run_id> | Cancel a run. |
POST | /api/agent/rollback | Roll back a snapshot. |
GET | /api/agent/history | Run history for the workspace. |
GET | /api/agent/prefs | Read user prefs. |
POST | /api/agent/prefs | Update user prefs. |
Budget
| Method | Path | Purpose |
|---|
POST | /api/budget/estimate | Pre-run cost estimate. |
GET | /api/budget/ledger?ws_id=… | Per-day cost history. |
Receipts
| Method | Path | Purpose |
|---|
GET | /api/receipts/chain-head?ws_id=… | Latest receipt hash. |
POST | /api/receipts/<run_id>/verify | Verify chain integrity. |
POST | /api/receipts/<run_id>/reground | Re-check findings against current state. |
Shell
| Method | Path | Purpose |
|---|
POST | /api/shell/run | Stream a shell command. |
POST | /api/shell/test | Run the project's tests. |
POST | /api/shell/suggest | LLM command suggestion. |
GET | /api/shell/jobs | List in-flight jobs. |
POST | /api/shell/cancel/<job_id> | Cancel a job. |
GET | /api/shell/recent | Recent commands. |
GET | /api/shell/ssh-hosts | SSH hosts from ~/.ssh/config. |
POST | /api/shell/ssh-run | Run a remote command. |
POST | /api/shell/ssh-pull | Pull a remote file. |
PTY
| Method | Path | Purpose |
|---|
POST | /api/pty/spawn | Spawn a PTY. |
| _ws_ | /api/pty/<id>/stream | TTY stream (WebSocket). |
MCP / Browser
| Method | Path | Purpose |
|---|
GET | /api/mcp | Tool registry. |
POST | /api/mcp | Invoke a tool. |
GET | /api/mcp/tokens | List MCP tokens. |
POST | /api/mcp/tokens | Set MCP token. |
POST | /api/browser/run | Browser smoke/flow/marketing. |
GET | /api/browser/allowlist | Read allowlist. |
PUT | /api/browser/allowlist | Update allowlist. |
Secrets
| Method | Path | Purpose |
|---|
GET | /api/secrets | List secret names. |
GET | /api/secrets/<name> | Reveal a secret. |
POST | /api/secrets/<name> | Set a secret. |
DELETE | /api/secrets/<name> | Delete a secret. |
POST | /api/secrets/rotate-master | Rotate master key. |
Notebook
| Method | Path | Purpose |
|---|
POST | /api/notebook/run/<nb_id>/<cell_id> | Execute a notebook cell. |
Collab (alpha)
| Method | Path | Purpose |
|---|
GET | /api/collab/activity?ws_id=… | Activity feed. |
GET | /api/collab/notifications | Unread notifications. |
POST | /api/collab/notifications/<nid>/read | Mark read. |
POST | /api/collab/invite | Invite a member. |
POST | /api/collab/request-review | Request review. |
POST | /api/collab/share-link | Create share link. |
Conventions
- All endpoints return JSON unless they're SSE streams.
- Errors are
{ "error": { "code": "…", "message": "…" } } with HTTP 4xx/5xx. - Timestamps are ISO 8601 UTC.
- IDs are opaque strings — don't parse them.
- Pagination via
?cursor=…&limit=… where applicable.
Total route count
The full app.py registers 436 routes as of this build. scripts/ci.sh job app-import reports the live count.