Server API Reference

This page documents the supported integration surface only.

Route Inventory

Instance

GET /api/

• Authentication: Optional
• Purpose: Returns instance metadata, public key, and current server mode.

Response:

• Includes status, version, public_key, name, public_url, and selfhosted.
• If the caller is authenticated, the payload may also include is_admin and license fields.

GET /api/health

• Authentication: No
• Purpose: Returns HTTP API and database health, plus optional diagnostics.

Response:

• Includes server.status, database.status, version, name, public_url, and public_key.
• Low-level live-sync counters are exposed under diagnostics.realtime.

Auth and Session

POST /api/auth/verify_key

• Authentication: No
• Purpose: Verifies a signed public-key challenge and returns tokens when the account is approved.

Request body:

• public_key: public key used for verification.
• signed_message: signature over the original verification message.
• message: original challenge text.
• server_challenge: optional challenge that the server should sign in its response.

Response:

• Returns verification status plus access_token and refresh_token when approved.
• Pending-approval accounts return approval_required without tokens.

POST /api/auth/create_session

• Authentication: No
• Purpose: Starts the current key-based login flow by issuing a challenge to sign.

Request body:

• public_key: required base58 public key.
• email: optional email hint for self-hosted or first-time login flows.

Response:

• Returns { success, challenge }.

Notes:

• The challenge is signed client-side and then sent to /api/auth/verify_session.

POST /api/auth/verify_session

• Authentication: No
• Purpose: Completes the challenge-based login flow and returns access and refresh tokens.

Request body:

• public_key: public key used during challenge creation.
• message: original challenge string.
• signature: signature over that challenge.
• server_challenge: optional caller-provided challenge to be signed by the server.
• email: optional email hint.

Response:

• Returns accessToken, refreshToken, server_public_key, and server identity fields.

POST /api/auth/refresh_token

• Authentication: Refresh token
• Purpose: Exchanges a refresh token for a new access token and refresh token pair.

Response:

• Returns { success, accessToken, refreshToken }.

POST /api/me

• Authentication: Yes
• Purpose: Returns the authenticated user's profile, subscriptions, entitlements, and usage summary.

Response:

• Includes identity fields, subscription and entitlement arrays, usage stats, and effective limits.

Sync and Realtime

GET /api/ws

• Authentication: Yes
• Purpose: DEPRECATED:Legacy websocket entrypoint only used for scan updates

Notes:

• Use /ws for the current live sync websocket path.

GET /ws

• Authentication: Yes
• Purpose: Primary WebSocket endpoint for live document sync, sync updates and more.

GET /sync/health

• Authentication: No
• Purpose: Returns sync subsystem health information.

GET /api/sync/delta

• Authentication: Yes
• Purpose: Lists changed and deleted blocks in a workspace since a given timestamp.

Query parameters:

• workspace_id: required workspace identifier.
• since: Unix milliseconds. Defaults to 0 if omitted or invalid.

Response:

• Returns changed_blocks, deleted_blocks, server_time, has_more, total_changed, and total_deleted.

POST /api/sync/push

• Authentication: Yes
• Purpose: Pushes YDoc updates for one or more blocks.

Request body:

• blocks: required array of { block_id, workspace_id, state_vector, update, sync_version }.

Response:

• Returns per-block push results and server_time.

POST /api/sync/pull

• Authentication: Yes
• Purpose: Requests missing YDoc updates or full state for one or more blocks.

Request body:

• blocks: required array of { block_id, state_vector, sync_version }.

Response:

• Returns per-block updates, full states for version mismatches, deletion markers, and server_time.

Heaps, Blocks

| POST | /api/heap/add | Yes | Creates a new workspace or heap. | | DELETE | /api/heap/:id | Yes | Deletes a workspace or heap. | | GET | /api/heap/stats/:id | Yes | Returns heap-level statistics. | | POST | /api/heap/changed_blocks | Yes | Returns blocks changed in a heap since a given marker. |

POST /api/workspaces

• Authentication: Yes
• Purpose: Lists workspaces owned by the authenticated user.

POST /api/block/:blockKey

• Authentication: Yes
• Purpose: Fetches one block with relations, apps, file metadata, and content.

POST /api/block_updates/:blockKey

• Authentication: Yes
• Purpose: Returns update history and YDoc payload for a block.

GET /api/trash/:heapId

• Authentication: Yes
• Purpose: Lists trashed blocks for a heap.

DELETE /api/trash/:heapId

• Authentication: Yes
• Purpose: Empties the trash for a heap.

POST /api/trash/:heapId/restore

• Authentication: Yes
• Purpose: Restores one or more blocks from trash.

POST /api/heap

• Authentication: Yes
• Purpose: Returns heap contents or heap-scoped block lists.

POST /api/heap_count

• Authentication: Yes
• Purpose: Returns heap-scoped block counts.

POST /api/heap/add

• Authentication: Yes
• Purpose: Creates a new workspace or heap.

DELETE /api/heap/:id

• Authentication: Yes
• Purpose: Deletes a workspace or heap.

GET /api/heap/stats/:id

• Authentication: Yes
• Purpose: Returns heap-level statistics.

POST /api/heap/changed_blocks

• Authentication: Yes
• Purpose: Returns blocks changed in a heap since a given marker.

Files and Uploads

GET /api/file/:key/thumbnail/:size/:slug

• Authentication: Yes or token query
• Purpose: Serves an image thumbnail for a file block.

GET /api/file/:key/video_thumbnail/:size/:position

• Authentication: Yes or token query
• Purpose: Serves a generated video thumbnail.

GET /api/file/:key/animated_thumbnail/:size/:slug

• Authentication: Yes or token query
• Purpose: Serves an animated thumbnail for supported formats.

GET /api/file/:key/raw/:slug

• Authentication: Yes or token query
• Purpose: Streams or downloads the raw file content.

GET /api/stream/:key/:slug

• Authentication: Yes or token query
• Purpose: Alternate stream-oriented file URL for media players.

POST /api/scan_folder

• Authentication: Yes
• Purpose: Starts a scan job for a specific folder path or heap.

POST /api/abort_scan

• Authentication: Yes
• Purpose: Stops an active scan job.

GET /api/active_scans

• Authentication: Yes
• Purpose: Lists currently active scan jobs.

POST /api/reindex_files

• Authentication: Yes
• Purpose: Triggers file index rebuilding.

POST /api/regenerate_file

• Authentication: Yes
• Purpose: Regenerates derived metadata for a file.

POST /api/upload/file/:heap_id/:block_id

• Authentication: Yes
• Purpose: Assigns a directly uploaded file to a block.

Request body:

• Multipart form upload with file payload and hash.

Response:

• Returns { status, block_id, file_hash, file_id }.

POST /api/upload/init/:heap_id/:block_id

• Authentication: Yes
• Purpose: Initializes a resumable upload for a block and file hash.

GET /api/upload/status/:heap_id/:block_id/:hash

• Authentication: Yes
• Purpose: Returns current resumable upload progress.

PUT /api/upload/chunk/:heap_id/:block_id/:hash/:index

• Authentication: Yes
• Purpose: Uploads one resumable chunk.

Response:

• Returns { status, index, size } when the chunk is accepted.

POST /api/upload/complete/:heap_id/:block_id/:hash

• Authentication: Yes
• Purpose: Finalizes a resumable upload and creates or updates metadata.

POST /api/upload/thumbnail/:block_id/:file_hash/:thumbnail_key

• Authentication: Yes
• Purpose: Uploads a thumbnail asset for a file.

Request body:

• Multipart form with thumbnail, type, and size.

GET /api/download/thumbnail/:block_id/:file_hash/:thumbnail_type/:thumbnail_size

• Authentication: Yes
• Purpose: Downloads a stored thumbnail.

GET /api/status/file/:heap_id/:block_id/:hash

• Authentication: Yes
• Purpose: Returns file upload status by heap, block, and content hash.