FractalEngine

API overview

The desktop app and the headless relay serve one HTTP API. It has three surfaces on the same port:

  • REST under /api/v1/ for the hierarchy, nodes, assets, queries and exports.
  • WebSocket at /ws for live scene subscriptions. After connecting, the server sends auth_required and the client has 5 seconds to send an auth message carrying a token.
  • MCP at POST /mcp, JSON-RPC 2.0, for AI agents. Tools are role-checked and scope-checked the same way as REST calls.

The desktop app listens on 127.0.0.1:8765, this computer only. Get a token as described in Using a hosted instance, then:

export FE_API=http://127.0.0.1:8765
export TOKEN=...   # a bearer token for the verse you want to use

The environment variables for opt-in features are in the README, and the full route list is in the repository’s fe-api notes (section “routes”).

Check that it is up

No token needed.

curl $FE_API/api/v1/health
# {"status":"ok"}

Read the hierarchy

Returns the verses, fractals, petals and nodes your token’s scope covers.

curl -H "Authorization: Bearer $TOKEN" $FE_API/api/v1/hierarchy

Create content

Responses use one envelope, {"ok": ..., "data": ...}, and a new object’s id is at data.id. The creation routes are POST /api/v1/verses, POST /api/v1/verses/{verse_id}/fractals, .../fractals/{fractal_id}/petals and .../petals/{petal_id}/nodes, each with a JSON body such as {"name":"My verse"}. Creating a verse needs a token that is not tied to an existing verse; bi-egress.md shows how to mint one for a headless relay.

Query your data

POST /api/v1/query runs a single read-only SELECT within the scope of your token. Limits are in Limits and behaviour.

curl -X POST $FE_API/api/v1/query \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sql":"SELECT * FROM node WHERE petal_id = '"'"'<petal id>'"'"'"}'

Export for BI tools

A token scoped to one petal can mint a signed, time-limited link to a Parquet or CSV export. The link needs no token, so you can paste it into DuckDB, Power BI or a spreadsheet.

curl -X POST $FE_API/api/v1/query/share \
  -H "Authorization: Bearer $PETAL_TOKEN" -H "Content-Type: application/json" \
  -d '{"sql":"SELECT * FROM node WHERE petal_id = '"'"'<petal id>'"'"'","format":"parquet","ttl_secs":3600}'
# the link is $FE_API/api/v1/shared/<data.token>

The project has verified this path end to end against DuckDB. Details, column layouts and axis conventions are in bi-egress.md.

Ask MCP what it offers

curl -X POST $FE_API/mcp \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

curl -X POST $FE_API/mcp \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

tools/list returns every tool the host offers, with its input schema; call one with tools/call and {"name": ..., "arguments": {...}}. Which tools appear depends on the host: the desktop app adds screenshot and camera tools and, behind opt-in flags, input and UI inspection tools. The extension tools list extensions, send them commands and manage their bindings. Installing one is never possible through REST or MCP.