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

OpenLoomi API Documentation

API Modules

OpenLoomi ships a local-first HTTP API served from the desktop app (port 3414, fallback 3515). All auth, Memory, AI, RAG, Loop, and Audit data live in a local SQLite database — your data stays on your machine and the OpenLoomi app is the source of truth. The only externally-routed auth path is the Composio OAuth broker that backs the Slack, GitHub, Google, Notion, Linear, HubSpot, LinkedIn, Jira, and Asana Connectors (see openloomi-connectors).

The remote-auth prefix is historical — those 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. Pair it with openloomi-loop (Loop state, decisions, channels, classifier rules, brief/wrap) and openloomi-memory (Memory search, KB, insights, entities, living connections) for the runtime surfaces used by Chat and Loop.

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)

Sandbox and network

If curl calls, the OpenLoomi CLI, or setup-status fail with network errors (e.g. ECONNREFUSED, ETIMEDOUT, "unreachable"), check whether Codex is running inside a sandbox before concluding the OpenLoomi desktop API is stopped. Codex network sandboxing can block:

• Loopback access to the host's localhost (e.g. http://localhost:3414 / http://localhost:3515).
• Outbound traffic to GitHub or other release endpoints used by install / update flows.

Request approval and retry the same call outside the sandbox. If the outside-sandbox retry succeeds, treat the in-sandbox failure as a sandbox artifact — not a real product problem. Do not recommend restarting OpenLoomi until the outside-sandbox checks also fail. See openloomi for the canonical sandbox / loopback probe.

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 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)
• Local-first: auth, Memory, AI, RAG, Loop, and Audit data live in a local SQLite database; the only externally-routed path is the Composio OAuth broker
• Dual authentication: Session cookies (web) and Bearer tokens (Tauri / CLI)
• RESTful JSON APIs with Zod validation
• SWR utilities for client-side data fetching
• OAuth support for Slack, Discord, X, HubSpot, LinkedIn, Notion
• RAG for Knowledge Base document upload + retrieval (openloomi-memory owns the user-facing surface)
• AI endpoints for chat, images, audio
• Loop for the proactive judgement engine — signals, decisions, cards, channels, classifier rules (see openloomi-loop)
• Memory search + raw-message access (full surface in openloomi-memory)
• Pet state mirror (read/write /api/pet/state)