Backend API & FastAPI Routers

Relevant source files

The following files were used as context for generating this wiki page:

• backend/main.py
• backend/routers/conversations.py
• backend/routers/memories.py
• backend/AGENTS.md
• backend/README.md
• AGENTS.md

The Omi backend is a Python-based infrastructure built primarily on the FastAPI framework. It serves as the central hub for processing real-time audio transcriptions, managing user memories, and orchestrating interactions between wearable devices, mobile applications, and desktop clients. The system utilizes a modular "router" architecture to separate concerns across different functional domains such as conversations, memories, apps, and authentication.

Sources: backend/AGENTS.md:16-20, README.md:94-110

Architecture Overview

The backend employs a 3-lane asynchronous architecture to ensure the event loop remains unblocked during heavy I/O or CPU-bound tasks. This is critical for maintaining high-performance real-time audio streaming and transcription pipelines.

• Lane 1 - Async HTTP: Uses shared httpx.AsyncClient pools for external integrations (webhooks, maps, STT).
• Lane 2 - Executors: Utilizes 7 purpose-specific thread pools (e.g., db_executor, llm_executor, storage_executor) to offload blocking operations.
• Lane 3 - Linting: Employs scanning tools to catch blocking calls in asynchronous routes.

Sources: backend/AGENTS.md:120-165

Data Flow Diagram

The following diagram illustrates the high-level request flow from a device through the FastAPI routers to various backend services.

Core Routers and Endpoints

The backend registers over 45 routers in main.py, each handling a specific domain of the Omi ecosystem.

Conversation Management

The /v1/conversations router handles the lifecycle of captured audio sessions, including CRUD operations, merging segments, and processing action items.

Endpoint	Method	Description
/v1/conversations	GET/POST	List or create conversation sessions.
/v1/conversations/{id}	GET/DELETE	Retrieve or delete a specific conversation.
/v1/conversations/merge	POST	Merge multiple segments into a single conversation.

Sources: backend/AGENTS.md:41-43, backend/routers/conversations.py

Memory and Fact Extraction

The /v3/memories router manages "User Facts" or learnings extracted from conversations. These are stored with categories, visibility settings, and encryption.

Endpoint	Method	Description
/v3/memories	GET	Retrieve user memories with semantic search support.
/v3/memories	POST	Manually create or trigger AI extraction of a memory.
/v3/memories/{id}	PATCH/DELETE	Update visibility or delete a specific fact.

Sources: backend/AGENTS.md:44-45, backend/routers/memories.py

Asynchronous Execution Strategy

The backend strictly follows rules for offloading blocking operations to prevent event loop starvation.

Executor Pool Assignments

Specific tasks are mapped to dedicated executors to prevent deadlocks and ensure predictable performance.

Executor	Purpose	Concurrent Workers
critical_executor	Auth gates, rate-limiting, Redis session ops.	8
db_executor	Firestore CRUD, Redis locks, Vector DB queries.	24
llm_executor	LLM API calls (OpenAI, Anthropic).	6
storage_executor	GCS uploads/downloads, audio chunk I/O.	128
postprocess_executor	Conversation post-processing and coordinators.	24

Sources: backend/AGENTS.md:144-160

Implementation Pattern

Endpoints use a specific pattern for calling blocking database or storage functions within an async def route:

# Example of correct offloading pattern
@router.post("/v1/example")
async def example_route(data: Schema, uid: str = Depends(get_current_user_uid)):
    # Offload blocking Firestore/Redis call to the db_executor
    result = await run_blocking(db_executor, database_function, uid, data)
    return result

Sources: backend/AGENTS.md:138-142, AGENTS.md:58-65

Authentication and Security

Authentication is primarily handled via Firebase and injected into routers using FastAPI's dependency injection system.

• HTTP Endpoints: Use uid: str = Depends(get_current_user_uid) to retrieve the authenticated user's ID.
• WebSockets: Must use WebSocketException(code=1008) for auth failures to avoid 5xx errors from Load Balancers.
• Data Protection: Segments and memories are encrypted at rest using AES-256-GCM. Direct database reads return opaque blobs that require per-user keys for decryption.

Sources: backend/AGENTS.md:104-115, backend/AGENTS.md:88-92

Summary

The Backend API and its FastAPI routers provide a robust, asynchronous interface for the Omi ecosystem. By strictly separating I/O-bound tasks into specialized thread pools and maintaining a modular router structure, the system supports complex real-time operations like diarization, transcription, and proactive memory extraction while remaining scalable and responsive.

Sources: backend/AGENTS.md:120-130, README.md:112-118