API Reference

The LoomBrain API is a REST API hosted on Cloudflare Workers.

Base URL

https://api.loombrain.com/api/v1

Authentication

All endpoints (except auth routes) require authentication via one of:

• Bearer token: Authorization: Bearer <access_token> — JWT with 15-minute expiry
• API key: Authorization: ApiKey <key> — HMAC-verified, no expiry

See Authentication for details.

Request format

• Content-Type: application/json for most endpoints
• Content-Type: multipart/form-data for file uploads
• All request bodies are validated with Zod schemas

Response format

Successful responses return JSON. List endpoints return paginated results:

{
  "data": [...],
  "total": 42,
  "page": 1,
  "per_page": 20
}

Error responses

Errors return JSON with an error field:

{
  "error": "NOT_FOUND",
  "message": "Node not found"
}

Common HTTP status codes:

| Status | Meaning | |--------|---------| | 200 | Success | | 201 | Created | | 204 | No content (successful deletion) | | 400 | Validation error | | 401 | Unauthorized — missing or invalid credentials | | 404 | Resource not found | | 413 | Payload too large | | 415 | Unsupported media type | | 426 | Upgrade required — CLI version too old | | 429 | Rate limited | | 500 | Internal server error |

CLI version header

The CLI sends an X-CLI-Version header with every request. The API may:

• Return 426 Upgrade Required if the CLI version is below the minimum
• Set X-Recommended-CLI-Version response header if a newer version is available

See CLI Upgrade for details.

Endpoint groups

| Group | Description | |-------|-------------| | Nodes | Knowledge graph node CRUD and search | | Captures | Content capture, upload, and lifecycle | | PARA | PARA item management | | Context | Session context and graph health | | Links | Node relationships and suggestions | | Graph | Graph visualization data | | Stats | Usage statistics |