HTTP API
Every endpoint the Krafa backend exposes, covering boards, memories, files, and the MCP handler.
The HTTP API is what the Krafa web app talks to. It's documented here for self-hosters and for anyone scripting against their own instance.
Everything except the MCP endpoint authenticates with a session cookie from Better Auth; there is no separate API key. The one credential designed for outside use is a board's MCP token, and it only works against /api/mcp. If you want programmatic read access to a taste profile, use MCP.
Requests without a valid session return 401 { "error": "unauthorized" }.
Boards
| Method | Path | Purpose |
|---|---|---|
GET | /api/boards | List your boards |
POST | /api/boards | Create a board. { name? }, defaults to Untitled |
GET | /api/boards/:id | Fetch one board with its nodes |
PUT | /api/boards/:id | Update { nodes?, name? } |
DELETE | /api/boards/:id | Delete a board and everything it owns |
GET | /api/boards/:id/share | Read sharing settings |
PUT | /api/boards/:id/share | Set { visibility, userIds? } |
POST | /api/boards/:id/mcp-token | Mint or return the board's MCP token |
PUT /api/boards/:id is what the canvas autosave calls, sending the full node array on a debounce.
Rotating an MCP token
curl -X POST https://app.krafa.ai/api/boards/BOARD_ID/mcp-token \
-H "Content-Type: application/json" \
-d '{"regenerate": true}'Without regenerate, the endpoint returns the existing token or mints one if the board has none. With it, the old token stops working immediately and every agent configured with it starts returning invalid token.
Rotation isn't currently surfaced in the app UI; this endpoint is the way to do it.
Memories
Scoped under a board. See Taste memories for what the fields mean.
| Method | Path | Purpose |
|---|---|---|
GET | /api/boards/:boardId/memories | List active memories |
PUT | /api/boards/:boardId/memories/:memoryId | Edit { statement } |
DELETE | /api/boards/:boardId/memories/:memoryId | Delete a memory |
POST | /api/boards/:boardId/memories/extract | Run extraction for { nodeId, content } |
POST | /api/boards/:boardId/memories/resolve | Resolve a conflict |
POST | /api/boards/:boardId/memories/prune | Delete memories sourced from { nodeIds } |
extract returns { memories, conflicts }. On an instance without ANTHROPIC_API_KEY it returns { memories: [], conflicts: [], disabled: true } rather than erroring.
resolve takes { choice, existingMemoryId, incoming, sourceNodeId? } where choice is one of:
choice | Effect |
|---|---|
keep | No-op. The existing memory stands |
replace | Marks the existing memory superseded and inserts the incoming one |
both | Keeps the existing memory and inserts the incoming one alongside it |
Files
| Method | Path | Purpose |
|---|---|---|
POST | /api/upload | Multipart upload, field file → { id, url } |
GET | /api/files/:id | Stream a file, with range request support |
Uploads are capped at 50 MB and stored in S3-compatible object storage.
Content helpers
Used by the canvas to render embeds. All are session-authenticated.
| Method | Path | Purpose |
|---|---|---|
GET | /api/unfurl?url= | Extract OG and meta tags for a link preview |
GET | /api/img?url= | Same-origin image proxy, for sources that block cross-origin loads |
GET | /api/tweet-article/:id | Fetch article content attached to an X post |
Imports
OAuth flows for the import sources. Each connect endpoint takes a boardId so the callback returns you to the board you started from.
| Method | Path |
|---|---|
GET | /api/x/connect?boardId= |
GET | /api/x/callback |
GET | /api/x/bookmarks |
GET | /api/pinterest/connect?boardId= |
GET | /api/pinterest/callback |
GET | /api/pinterest/boards |
GET | /api/pinterest/boards/:id/pins |
Access tokens are encrypted at rest with the instance's auth secret.
Auth and health
| Method | Path | Purpose |
|---|---|---|
GET/POST | /api/auth/* | Better Auth: magic link, GitHub, Google, organizations, sessions |
GET | /api/health | Liveness plus a database connectivity check |
GET | /api | Service name and version |
MCP
| Method | Path | Purpose |
|---|---|---|
ALL | /api/mcp | MCP Streamable HTTP, authenticated by board bearer token |
The only endpoint intended for clients outside the app. Full tool schemas are in the MCP server reference.