heaper
Docs

Client HTTP API

The client HTTP API is a local automation surface exposed by the Electron desktop app. It is not the same thing as the remote server API. This allows you to create local automations that can import data like a webclipper or import script.

Availability

This API is Desktop-only for obvious reasons, a port to mobile is possible but not yet implemented because of the lack of useful benefits compared to the server API on low spec mobile devices.

In the app, enable it under:

Settings → Local API

When enabled, the main process starts a localhost HTTP server and generates a per-installation token.

Host, Port, and Discovery

The API binds to:

127.0.0.1

The default port is:

19532

If that port is already taken, the app falls back to a random free port and writes the actual port to a discovery file:

~/.heaper/api.json

The discovery file contains the current port, process ID, and startup time. The CLI reads this file to find the local API automatically.

Authentication

All endpoints except GET /api/health require:

Authorization: Bearer <local-api-token>

You can copy or regenerate the token from the same Local API settings panel.

Safety Model

This API is designed for local tooling, not remote exposure:

  • it listens on localhost only
  • it uses a separate local API token, not the server JWT flow
  • the raw SQL endpoint only allows SELECT statements, edits are all going through the crdt's in the client to sync seamlessly with the server.

If you expose this port beyond localhost yourself, you are responsible for the security boundary.

Quick Start with curl

curl http://127.0.0.1:19532/api/health

curl http://127.0.0.1:19532/api/heaps \
  -H 'Authorization: Bearer <local-api-token>'

curl http://127.0.0.1:19532/api/search?q=notes \
  -H 'Authorization: Bearer <local-api-token>'

Quick Start with fetch

const token = process.env.HEAPER_TOKEN;

const res = await fetch('http://127.0.0.1:19532/api/heaps', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const heaps = await res.json();
console.log(heaps);

Data Model Notes

This API reads from the local desktop app data store, including local workspace, block, relation, file, thumbnail, and app tables. It is intended for developer tooling and inspection, not as a stable public cloud API.

Useful endpoints include:

  • GET /api/heaps
  • GET /api/heaps/:id/blocks
  • GET /api/blocks/:id
  • GET /api/search
  • POST /api/query
  • POST /api/blocks

Reference

Use the generated route reference for the exact local endpoint inventory: