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