openloomi-api

name

openloomi-api

description

openloomi HTTP API reference (local-first, served from the OpenLoomi Desktop app at http://localhost:3414). Use when working with openloomi backend routes — auth, AI, files, integrations, RAG, memory, Loop, pet, workspace, platform callbacks. Triggers: API endpoints, backend routes, /api/*, local API, port 3414, integrations REST, OAuth start, RAG search, loop state, memory search, pet state, audit logs

Note: If OpenLoomi readiness is unknown, use openloomi-setup first. If OpenLoomi Desktop is not installed, follow Getting Started.

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

Module	Base Path	Routes	Description
Auth	/api/auth/*, /api/remote-auth/*, /api/remote-feedback/*	6	Guest session, token, user probe, feedback
AI	/api/ai/*	5	Chat, images, audio, embeddings
Audit	/api/audit/*	1	Audit log retrieval
Chat Insights	/api/chat-insights/*	1	Per-chat insight records
Chronicle	/api/chronicle/*	7	Meeting detection, analysis, memories
Contacts	/api/contacts/*	1	Contact query
DB Init	/api/db/*	1	Bootstrap database
Files	/api/files/*	8	File storage, upload, download
Insight Tabs	/api/insight-tabs/*	3	Tab CRUD + reorder
Integrations	/api/integrations/*	9	OAuth + connected accounts
Listeners	/api/listeners/*	1	Listener cleanup
LLM Usage	/api/llm/*	1	Usage summary
Loop	/api/loop/*	24	Attention loop, decisions, channels, classifier rules
Markmap	/api/markmap/*	1	Markmap generation
Memory

Platform Callback Modules

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

Platform	Base Path	Routes
Slack	/api/slack/*	2
Discord	/api/discord/*	2
Feishu (Lark)	/api/feishu/*	1
DingTalk	/api/dingtalk/*	1
QQ Bot	/api/qqbot/*	1
Weixin (WeChat)	/api/weixin/*	4
Telegram	/api/telegram/*	4
WhatsApp	/api/whatsapp/*	2
iMessage	/api/imessage/*	2
HubSpot	/api/hubspot/*	1
LinkedIn	/api/linkedin/*	1
Notion	/api/notion/*	1

---

Endpoints Reference

Auth Module

Method	Endpoint	Description
POST	/api/auth/set-token	Set auth token
POST	/api/auth/clear-auth-cookie	Clear session
POST	/api/auth/token	Issue session token
POST	/api/remote-auth/guest	Create anonymous guest session
GET	/api/remote-auth/user	Get current user (also used by plugin probe)
PUT	/api/remote-auth/user	Update user info
POST	/api/remote-feedback	Submit feedback

Messages Module

Method	Endpoint	Description
GET	/api/messages	List messages
POST	/api/messages	Send message
GET	/api/messages/sync	Sync messages
GET	/api/messages/check	Check message status
GET	/api/messages/raw	Get raw message

Files Module

Method	Endpoint	Description
GET	/api/files/list	List files
GET	/api/files/[id]	Get file by ID
GET	/api/files/download	Download file
POST	/api/files/upload	Upload file
POST	/api/files/save	Save file
GET	/api/files/usage	Get storage usage
GET	/api/files/insights/download	Download insights file
POST	/api/files/insights/save	Save insights

Storage Module

Method	Endpoint	Description
GET	/api/storage/disk-usage	Get disk usage
POST	/api/storage/cleanup	Cleanup storage
GET	/api/storage/sessions	List sessions
GET	/api/storage/sessions/[taskId]	Get session by task ID
DELETE	/api/storage/sessions/[taskId]	Delete session

Integrations Module

Method	Endpoint	Description
GET	/api/integrations/accounts	List connected accounts
GET	/api/integrations/slack/oauth/start	Start Slack OAuth
GET	/api/integrations/slack/oauth/exchange	Exchange Slack OAuth code
GET	/api/integrations/discord/oauth/start	Start Discord OAuth
GET	/api/integrations/discord/oauth/exchange	Exchange Discord OAuth code
GET	/api/integrations/x/oauth/start	Start X OAuth
GET	/api/integrations/hubspot/oauth/start	Start HubSpot OAuth
GET	/api/integrations/linkedin/oauth/start	Start LinkedIn OAuth
GET	/api/integrations/notion/oauth/start	Start Notion OAuth

Platform Callbacks

Platform	Module	Sample Endpoint
Slack	/api/slack/*	OAuth + listener endpoints under the module
Discord	/api/discord/*	OAuth + listener endpoints under the module
Feishu	/api/feishu/*	POST /api/feishu/listener/init
DingTalk	/api/dingtalk/*	POST /api/dingtalk/listener/init
QQ Bot	/api/qqbot/*	POST /api/qqbot/listener/init
Weixin (WeChat)	/api/weixin/*	POST /api/weixin/listener/init
Telegram	/api/telegram/*	POST /api/telegram/user-listener/init
WhatsApp	/api/whatsapp/*	POST /api/whatsapp/register-socket
iMessage	/api/imessage/*	POST /api/imessage/init-self-listener
HubSpot	/api/hubspot/*	OAuth start under /api/hubspot/...
LinkedIn	/api/linkedin/*	OAuth start under /api/linkedin/...
Notion	/api/notion/*	OAuth start under /api/notion/...

RAG Module

Method	Endpoint	Description
GET	/api/rag/search	Search documents
GET	/api/rag/stats	Get RAG statistics
GET	/api/rag/documents	List documents
GET	/api/rag/documents/[documentId]	Get document
GET	/api/rag/documents/[documentId]/binary	Get document binary
DELETE	/api/rag/documents/[documentId]	Delete document
POST	/api/rag/upload	Upload document
POST	/api/rag/upload/init	Initialize upload
POST	/api/rag/upload/chunk	Upload chunk
POST	/api/rag/upload/complete	Complete upload
POST	/api/rag/upload/async	Async upload
GET	/api/rag/upload/async/status	Check async upload status

Workspace Module

Method	Endpoint	Description
GET	/api/workspace/artifacts	List artifacts
GET	/api/workspace/files	List files
GET	/api/workspace/file/[...path]	Get file by path
GET	/api/workspace/preview	Preview artifact
GET	/api/workspace/external-preview	External preview
GET	/api/workspace/pptx-preview/[taskId]/[...path]	Preview PPTX artifact
GET	/api/workspace/skills	List skills
GET	/api/workspace/skills/[skillId]	Get skill
POST	/api/workspace/skills	Create skill
PUT	/api/workspace/skills/[skillId]	Update skill
DELETE	/api/workspace/skills/[skillId]	Delete skill
POST	/api/workspace/skills/toggle	Toggle skill
POST	/api/workspace/skills/upload	Upload skill
GET	/api/workspace/skills/metadata	Get skill metadata

AI Module

Method	Endpoint	Description
POST	/api/ai/v1/chat/completions	Chat completions (streaming)
POST	/api/ai/v1/messages	Messages API
POST	/api/ai/v1/images/generations	Generate images
POST	/api/ai/v1/images/lifestyle/generate	Lifestyle image generate
POST	/api/ai/v1/images/lifestyle/compose	Lifestyle image compose

Chronicle Module

Method	Endpoint	Description
POST	/api/chronicle/analyze	Run chronicle analysis
GET	/api/chronicle/memories	List memories
GET	/api/chronicle/memories/[memoryId]	Get a memory
DELETE	/api/chronicle/memories/[memoryId]	Delete a memory

Insight Tabs Module

Method	Endpoint	Description
GET	/api/insight-tabs	List insight tabs
POST	/api/insight-tabs	Create insight tab
PUT	/api/insight-tabs/[tabId]	Update tab
POST	/api/insight-tabs/reorder	Reorder tabs

Chat Insights Module

Method	Endpoint	Description
GET	/api/chat-insights	Get chat insights

Memory Module

Method	Endpoint	Description
GET	/api/memory/search	Search memory
GET	/api/memory/raw-messages	Get raw messages

Native Module

Method	Endpoint	Description
GET	/api/native/providers	List native providers
GET	/api/native/skills	List native skills
POST	/api/native/agent	Agent invocation
POST	/api/native/agent/password	Agent password
POST	/api/native/agent/permission	Agent permission

Pet Module

Method	Endpoint	Description
GET	/api/pet/state	Read pet state
POST	/api/pet/state	Write pet state

Loop Module (highlights)

24 routes total. Top-level surfaces:

Endpoint	Description
GET /api/loop/connectors	Connector status
GET /api/loop/state	Loop state
POST /api/loop/tick	Advance loop tick
POST /api/loop/activation	Trigger activation
GET /api/loop/preferences	Loop preferences
GET /api/loop/brief / GET /api/loop/brief/content	Brief delivery
GET /api/loop/wrap / GET /api/loop/wrap/content	Wrap delivery
GET /api/loop/channels / GET /api/loop/channels/[id]	Channels
GET /api/loop/types / GET /api/loop/types/[id]	Loop types
GET /api/loop/decisions / GET /api/loop/decision/[id]	Decisions
POST /api/loop/action/schedule / GET /api/loop/action/[id]	Actions
GET /api/loop/action/by-decision/[id]	Actions by decision
GET /api/loop/classifier-rules[/...]	Classifier rules + dry-run
GET /api/loop/card/[id]	Card
POST /api/loop/dev/reset / GET /api/loop/dev/scene	Dev tooling

Agent Goal Module (read-only highlights)

Endpoint	Description
GET /api/agent-goals/active	Active, paused, and blocked Goals across the authenticated owner's chats
GET /api/agent-goals?runtimeSessionId=...	Goals for one Runtime Session
GET /api/agent-goals/[goalId]?runtimeSessionId=...	Ordered steps and progress for one Goal

Other Modules (single-route or paired)

Module	Endpoints
Audit	GET /api/audit/logs
Contacts	GET /api/contacts
DB	POST /api/db/init
Listeners	POST /api/listeners/cleanup
LLM Usage	GET /api/llm/usage/summary
Markmap	POST /api/markmap
Proxy	GET /api/proxy/css, GET /api/proxy/js

---

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

Code	Meaning
200	Success
400	Bad Request - Invalid input
401	Unauthorized - Not authenticated
403	Forbidden - Insufficient permissions
404	Not Found
429	Too Many Requests
500	Internal Server Error

---

AI/Agent Usage

Local API Access

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

Environment	Base URL
User Local Desktop	http://localhost:3414
User Local Desktop (fallback)	http://localhost: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"


TOKEN=$( ~/.openloomi/token |  -d)
curl -X POST http://localhost:3414/api/remote-feedback \
  -H  \
  -H  \
  -d 

---

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)