API overview#

The Mafold API is an HTTP + WebSocket interface shaped after Telegram's Bot API: every method lives at its own URL, takes a JSON body, and returns a uniform envelope.

Base URL#

In development the server listens on port 4000:

http://localhost:4000

A plain-text health check is available at GET /health (returns ok).

Authentication#

Every endpoint except /api/signIn requires a bearer token in the Authorization header.

Authorization: Bearer dev:<username>

In development the token is simply dev:<username> — the value returned as access_token from signIn. WebSocket connections pass the same token as a query parameter: ?token=dev:<username>.

Request format#

• Method is always POST (except the WebSocket upgrade and /health).
• Body is JSON with snake_case fields.
• Content-Type: application/json.

Response envelope#

Every endpoint (with one exception, uploadFile) wraps its payload in a uniform envelope.

On success — HTTP 200:

{ "ok": true, "result": { /* method-specific payload */ } }

On failure — HTTP status mirrors error_code:

{ "ok": false, "error_code": 404, "description": "not found: conversation" }

See Errors for the full code list.

Conventions#

Method index#