Client HTTP API Reference

These are the local HTTP endpoints exposed by the Electron desktop app. All endpoints except GET /api/health require Authorization: Bearer <local-api-token>.

GET /api/health

• Authentication: No
• Purpose: Lightweight health probe for the local API server.

Response:

• Returns { "status": "ok" } when the local API process is responding.

GET /api/info

• Authentication: Yes
• Purpose: Returns app version, current local API port, and basic local DB counts.

Response:

• Includes version, port, blocks, workspaces, and files.

GET /api/heaps

• Authentication: Yes
• Purpose: Lists local workspaces ordered by last activity.

Response:

• Returns an array of workspace rows with id, block_id, title, icon, type, and timestamps.

GET /api/heaps/:id

• Authentication: Yes
• Purpose: Returns one local workspace by ID.

Response:

• Returns the matching workspace row.
• Returns 404 if the workspace does not exist.

GET /api/heaps/:id/blocks

• Authentication: Yes
• Purpose: Lists blocks in a workspace, with optional type filter, paging, and local FTS query.

Query parameters:

• type: optional block type filter.
• limit: max rows, capped at 500 by the implementation.
• offset: pagination offset.
• q: optional full-text prefix search term within the heap.

Response:

• Returns { blocks, total, limit, offset }.

GET /api/blocks/:id

• Authentication: Yes
• Purpose: Returns a single block plus local relations, backlinks, files, thumbnails, apps, and attributes.

Response:

• Includes block fields such as id, title, text, type, workspace_id, timestamps, relations, backlinks, files, apps, available_views, global_filters, and attributes.
• relations and backlinks now include display-oriented fields like display_title, text_excerpt, and file_name, plus pagination metadata in relations_pagination and backlinks_pagination.
• Query params: limit, offset, and optional view=<view-id-or-name> to embed paginated filtered view results.

GET /api/blocks/:id/views/:viewId

• Authentication: Yes
• Purpose: Returns paginated block results for one saved app view using that view's filter and heap-filter settings.
• Query params: limit, offset.
• Response: { view, items, total, limit, offset, global_filters }.

GET /api/search

• Authentication: Yes
• Purpose: Runs local full-text search across blocks, optionally scoped to one heap.

Query parameters:

• q: required search term.
• heap: optional workspace filter.
• limit: max rows, capped at 500.
• offset: pagination offset.

Response:

• Returns { results, total, limit, offset }.

POST /api/query

• Authentication: Yes
• Purpose: Executes a read-only SQL query against the local database.

Request body:

• sql: required SQL string. Only SELECT statements are accepted.
• params: optional positional parameter array.

Response:

• Returns { rows }.

Notes:

• Non-SELECT statements are rejected with 403.

POST /api/blocks

• Authentication: Yes
• Purpose: Creates a new block in the local app through the Rust block creation path.

Request body:

• workspace_id: required destination workspace.
• title: optional block title.
• content: optional text content.
• relations: optional array of { to_id, type }.

Response:

• Returns { id, success } with HTTP 201 on success.

GET /api/tags

• Authentication: Yes
• Purpose: Lists tag blocks used in a heap.

Query parameters:

• heap: required workspace ID.

Response:

• Returns an array of distinct tag blocks with id, title, icon, and color.