Note: If you haven't downloaded or installed openloomi yet, please refer to Getting Started for installation instructions.

OpenLoomi API Documentation

API Modules

All auth routes resolve against the local SQLite database. There is no cloud dependency — openloomi is fully self-contained. The remote-auth prefix is historical (the routes once proxied to a cloud server); today they are the canonical local endpoints, and the Claude/Codex plugin bridge uses /api/remote-auth/user as a port-discovery + auth-handshake probe.

This reference covers 131 route handlers under 36 top-level /api/* modules (auto-surveyed from apps/web/app/api/).

Functional Modules

Platform Callback Modules

Each integration platform has its own /api/<platform>/* module:

Endpoints Reference

Auth Module

Messages Module

Files Module

Storage Module

Integrations Module

Platform Callbacks

RAG Module

Workspace Module

AI Module

Chronicle Module

Insight Tabs Module

Chat Insights Module

Memory Module

Native Module

Pet Module

Loop Module (highlights)

24 routes total. Top-level surfaces:

Other Modules (single-route or paired)

Error Handling

Error Response Format

// API errors return standard HTTP status codes
{
  error: string;      // Error message
  code?: string;       // Error code for programmatic handling
  cause?: string;      // Additional context
}

Common Status Codes

AI/Agent Usage

Local API Access

When running openloomi desktop app, the local API server runs on port 3414 (fallback: 3515):

Authentication Token

The auth token is stored at ~/.openloomi/token (base64 encoded JWT). You must decode it before use:

# Decode base64 to get JWT token
TOKEN=$(cat ~/.openloomi/token | base64 -d)

# Verify token contents (decodes JWT payload)
echo "$TOKEN" | cut -d'.' -f2 | base64 -d 2>/dev/null | python3 -m json.tool

curl Examples

Important: All authenticated requests require the token to be base64 decoded first.

# Helper: Get decoded token
TOKEN=$(cat ~/.openloomi/token | base64 -d)

# 1. Check AI API status (no auth required)
curl http://localhost:3414/api/ai/chat

# 2. Get current user info (also used by Claude/Codex plugin as a port-discovery probe)
TOKEN=$(cat ~/.openloomi/token | base64 -d)
curl http://localhost:3414/api/remote-auth/user \
  -H "Authorization: Bearer $TOKEN"

# 3. Create an anonymous guest session (no credentials)
curl -X POST http://localhost:3414/api/remote-auth/guest \
  -H "Content-Type: application/json" \
  -d '{}'

# 4. Chat with AI (streaming)
TOKEN=$(cat ~/.openloomi/token | base64 -d)
curl -X POST http://localhost:3414/api/ai/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello!"}],"stream":true}'

# 5. Get chat insights (requires chatId)
TOKEN=$(cat ~/.openloomi/token | base64 -d)
curl "http://localhost:3414/api/chat-insights?chatId=xxx" \
  -H "Authorization: Bearer $TOKEN"

# 6. Search RAG documents
TOKEN=$(cat ~/.openloomi/token | base64 -d)
curl -X POST http://localhost:3414/api/rag/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"search term","limit":5}'

# 7. List workspace skills
TOKEN=$(cat ~/.openloomi/token | base64 -d)
curl http://localhost:3414/api/workspace/skills \
  -H "Authorization: Bearer $TOKEN"

# 8. Submit feedback
TOKEN=$(cat ~/.openloomi/token | base64 -d)
curl -X POST http://localhost:3414/api/remote-feedback \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Feedback message","email":"user@example.com"}'

Summary

• 131 route handlers across 22 functional modules + 12 platform callback modules + 2 cross-cutting modules (proxy, db)
• Fully self-contained: all auth, data, AI, and sync run locally — no cloud dependency
• Dual authentication: Session cookies (web) and Bearer tokens (Tauri)
• RESTful JSON APIs with Zod validation
• SWR utilities for client-side data fetching
• OAuth support for Slack, Discord, X, HubSpot, LinkedIn, Notion
• RAG for document retrieval and search
• AI endpoints for chat, images, audio
• Loop for attention loop, decisions, channels, classifier rules
• Pet state mirror (read/write /api/pet/state)