One API, two deployments:
- Self-hosted (
forked-server):http://localhost:8080, optional static bearer token (FORKED_TOKEN). - forked cloud:
https://api.forked.run, API key per account (Authorization: Bearer fk_live_…).
Both are fed through the same dispatcher (forked-api), so routes, bodies
and error shapes are identical by construction. Switch between them by
changing baseUrl.
All bodies are JSON. Hashes are 64-char lowercase hex. Session and branch
names match [A-Za-z0-9._-]{1,128}.
Non-2xx responses carry:
{ "error": { "code": "conflict", "message": "…" } }| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request |
bad name, hash, JSON or query parameter |
| 401 | unauthorized |
missing/invalid credentials |
| 404 | not_found |
session, branch or commit does not exist |
| 404 | unknown_route |
no such endpoint |
| 409 | conflict |
branch moved concurrently (re-read head, retry) |
| 409 | session_exists / branch_exists |
create collided |
| 409 | effect_mismatch |
effect key already recorded with a different payload |
| 413 | payload_too_large |
body over 16 MiB |
| 429 | rate_limited |
cloud only: plan limit reached |
| 500 | internal / storage_error |
server-side failure |
→ { "status": "ok" }
Create a session with an empty state tree and a main branch.
Body (optional): { "session_id": "my-run-42" }, omit to get a generated id.
→ { "session_id": "…", "branch": "main", "head": "<hash>" }
→ { "branches": [ { "name": "main", "head": "<hash>" } ] }
Materialize the branch's full state.
→ { "head": "<hash>", "state": { "key": <value>, … } }
{
"ops": [
{ "op": "put", "key": "plan", "value": ["draft", "send"] },
{ "op": "delete", "key": "scratch" }
],
"meta": { "message": "optional metadata" },
"effects": [],
"expected_head": "<hash, optional>"
}expected_head enables optimistic concurrency: if the branch has moved,
nothing is written and you get 409 conflict. Omit it to commit on the
current head. effects records effect entries atomically with the commit
without an idempotency check, use /effects when you want
effectively-once semantics.
→ { "head": "<new hash>" }
Body: { "branch": "experiment" } → { "branch": "experiment", "head": "<hash>" }
O(1): writes one ref, copies nothing.
Rewind the branch to an earlier commit of the same session.
Body: { "commit": "<hash>" } → { "branch": "…", "head": "<hash>" }
History past the rewind point stays reachable (anchored); effects recorded
there remain visible to /effects.
Newest first. → { "entries": [ Commit, … ] } where Commit is:
{ "hash": "…", "parent": "…|null", "root": "…", "meta": {}, "effects": [] }Structural diff of two commits' states (shared subtrees are skipped by hash).
→ { "entries": [ { "key": "step", "change": "modified", "old": 1, "new": 2 } ] }
change ∈ added (only new), removed (only old), modified (both).
The whole session for visualization: every branch, rewind anchor, and reachable commit.
→ { "branches": [{name, head}], "anchors": ["<hash>"], "commits": [Commit, …] }
Record a side effect idempotently (session-wide, across branches and rewinds).
{
"branch": "main",
"key": "send-email:42",
"kind": "email.send",
"payload": { "to": "user@example.com" },
"result": { "message_id": "abc" }
}→ first time: { "status": "recorded", "record": {…}, "commit": "<hash>" }
→ replay: { "status": "already_recorded", "record": {…} } with the
original stored result, don't re-run the effect, use record.result.
→ same key, different payload: 409 effect_mismatch. The stored result
belongs to the old input, so it is not replayed. Build keys from whatever
identifies the input (e.g. charge:u-77:order-9), so new input gets a new
key.
Look up an effect by idempotency key without recording anything.
→ { "record": { "key", "kind", "payload", "result" } } or { "record": null }
The effectively-once recipe for performing a side effect (strict when a session has one writer at a time, forked cloud serializes writers per session; see FORMAT.md §6 for the concurrent-writer caveat):
GET /effects?key=…, if a record exists, reuse itsresult, do not re-run the work (after checking itspayloadmatches yours; the TS SDK'sfindEffect(key, { payload })does this for you).- Otherwise do the work.
POST /effectswith the observed result. If a concurrent writer beat you to it, the response isalready_recordedwith their stored result, use that one.