REST API
The ForgeDeck local REST API — endpoints, auth, and the write model.
Embed
<a href="https://docs.forgedeck.net/rest-api"><img src="https://docs.forgedeck.net/_api/public/orgs/db9cb8ff-b606-46cf-bbcd-02c8f8a9a3e2/spaces/6f417400-93ca-41a8-a914-df2ae3981dc6/pages/f676cba8-b473-41c8-8651-7d49553b2565/social-card.svg?v=3e7ae33eec8b" alt="REST API" width="600" height="315"></a>ForgeDeck runs a small REST API in-app, bound to 127.0.0.1. It's the same core the desktop UI and the MCP server use — three transports over one backend (projects, tasks, terminals, memory, git). It's the integration target for the TypeScript SDK.
Enable it
The server is off by default. Open Settings → API and:
Toggle Enabled (a bearer token is generated on first enable).
Optionally toggle Allow writes — reads work without it; mutating routes (create task, prompt agent, …) require it, so a read-only token is safe to share.
Copy the Base URL (
http://127.0.0.1:47379/api) and Token.
It only ever binds to loopback and rejects any request without the token.
Auth
Send the token as a bearer header on every request except GET /api/health:
curl http://127.0.0.1:47379/api/projects \
-H "Authorization: Bearer YOUR_TOKEN"Endpoints
Method | Path | Notes |
|---|---|---|
|
| liveness + version (no token) |
|
| list projects |
|
| list rooms |
|
| list tasks |
|
| create a task — write |
|
| set |
|
| list panes ( |
|
| scrollback tail + agent status |
|
| live agent status |
|
| type |
|
| send a |
|
| open a pane — write |
|
| semantic + keyword memory search |
|
| git status for the project |
key accepts enter, up, down, left, right, tab, shift-tab, escape, space, backspace, ctrl-c, ctrl-d, y, n — enough to answer any interactive prompt a human would.
Drive a running agent
The powerful pattern: read a pane, see what the agent is stuck on, and answer it.
# What is the agent doing / asking?
curl http://127.0.0.1:47379/api/terminals/SESSION_ID \
-H "Authorization: Bearer YOUR_TOKEN"
# Answer a free-text prompt (Enter is sent by default)
curl -X POST http://127.0.0.1:47379/api/terminals/SESSION_ID/input \
-H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{"text":"yes, proceed"}'
# Or press a single key to pick a menu option / confirm
curl -X POST http://127.0.0.1:47379/api/terminals/SESSION_ID/key \
-H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{"key":"enter"}'Errors
Non-2xx responses return { "error": "message" }. Common cases: 401 (bad/missing token), 403 (writes disabled), 400 (missing field), 404 (unknown id/route).
Prefer types? Use the @forgedeck/sdk client instead of raw curl.