Server API

The server API is the remote integration surface for Heaper. Use it when you are talking to a self-hosted instance.

Base URL

Most examples assume a server base URL like:

https://your-heaper.example.com

Server routes live under /api, for example:

curl https://your-heaper.example/api/health

Authentication

The server API uses bearer tokens:

Authorization: Bearer <access-token>

The middleware accepts the token from the Authorization header and validates it as an EdDSA-signed JWT. For file-serving style integrations, the backend also accepts token in the query string, but header-based auth is the normal developer path.

For current self-hosted and key-based flows, the main login pattern is:

POST /api/auth/create_session with the user's public key.
Sign the returned challenge client-side.
POST /api/auth/verify_session with the signature.
Use the returned accessToken for normal API requests.
Refresh with POST /api/auth/refresh_token using a refresh token bearer header.

The email/password login is only accessible to heaper.de cloud accounts, this removed the need for email servers in selfhosted environments which are basically hell to host and maintain.

Request and Response Conventions

JSON request bodies are used for most write and query-style endpoints.
Successful responses are JSON unless the endpoint serves binary file content.
Auth failures usually return 401 Unauthorized.
Permission failures usually return 403 Forbidden.
Routes under the new auth namespace are rate limited. These stricter for auth than for general data access.
CORS is enabled by middleware and mirrors the request origin, for compatibility with all devices and browsers.

Main Workflows

Instance Discovery and Health

Use these first:

GET /api/ returns instance metadata such as version, public key, public URL, and self-hosted status.
GET /api/health returns server and database health.

curl https://your-heaper.example/api/
curl https://your-heaper.example/api/health

Session Creation

Create a key-based auth challenge:

curl -X POST https://your-heaper.example/api/auth/create_session \
  -H 'Content-Type: application/json' \
  -d '{"public_key":"<base58-public-key>"}'

Verify the signed challenge:

curl -X POST https://your-heaper.example/api/auth/verify_session \
  -H 'Content-Type: application/json' \
  -d '{
    "public_key":"<base58-public-key>",
    "message":"<challenge>",
    "signature":"<base58-signature>"
  }'

Sync

Heaper exposes HTTP delta sync endpoints alongside WebSocket-based live sync.

GET /api/sync/delta asks what changed in a heap since a timestamp.
POST /api/sync/push uploads YDoc updates.
POST /api/sync/pull asks the server for missing updates or full state.
GET /ws is the live sync WebSocket endpoint used by the app.

Example delta request:

curl 'https://your-heaper.example/api/sync/delta?workspace_id=<workspace-id>&since=0' \
  -H 'Authorization: Bearer <access-token>'

Workspaces, Blocks, and Views

The content model is block-based. The main routes let you:

list heaps
fetch a block with relations and files
search and query blocks within a heap
create a block
editing of blocks is handled via crdt's in the client to sync seamlessly with the server. (thin wrappers to let this happen just with requests are planned)

Example:

curl -X POST https://your-heaper.example/api/heaps \
  -H 'Authorization: Bearer <access-token>'

curl -X POST https://your-heaper.example/api/block/<block-id> \
  -H 'Authorization: Bearer <access-token>'

Files and Uploads

The server API supports metadata queries, scan jobs, direct file assignment, resumable uploads, thumbnail upload/download, and authenticated raw file serving.

Resumable upload flow:

POST /api/upload/init/:heap_id/:block_id
PUT /api/upload/chunk/:heap_id/:block_id/:hash/:index
POST /api/upload/complete/:heap_id/:block_id/:hash

Reference

Use the reference page for the exact supported route inventory:

Server API Reference