# Desktop Local API

> **Status:** Active
> **Last updated:** 2026-07-05

## Overview

Electron hosts an optional **localhost HTTP API** that exposes read-only access to the local SQLite database, proxies login to allowed signaling servers, and serves bundled Docusaurus documentation offline.

## Responsibilities

| Layer | Owns |
|-------|------|
| Electron `api/router.ts` | HTTP routes, bearer token store, CQRS query dispatch |
| Desktop settings | Enable/disable Local API, port, allowed signal servers |
| `docs-site` build | Static bundle mounted at `/docusaurus/*` |

## Trust boundary

Separate **in-memory bearer tokens** from signaling-server session tokens. Login via Local API issues a local token; read routes require `Authorization: Bearer`. See [authentication.md](authentication.md).

## Routes (summary)

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/api/health` | No | Local API liveness |
| GET | `/api/openapi.json`, `/docs`, `/scalar/api-reference.js` | No | API docs (Scalar) |
| GET | `/docusaurus/*` | No | In-app documentation site |
| POST | `/api/auth/login` | No | Proxy to configured signaling server; returns local bearer |
| POST | `/api/auth/logout` | Bearer | Revoke local token |
| GET | `/api/profile` | Bearer | Current user profile |
| GET | `/api/rooms`, `/api/rooms/{roomId}`, `.../users`, `.../messages`, `.../bans` | Bearer | Read-only room data |
| GET | `/api/messages/{messageId}`, `.../reactions`, `.../attachments` | Bearer | Message graph |
| GET | `/api/users/{userId}`, `/api/attachments`, `/api/plugin-data` | Bearer | User + plugin data reads |
| GET | `/api/meta/{key}` | Bearer | Meta key lookup |

Database routes return **503** when SQLite is not initialised.

## IPC

- `get-local-api-status`, `open-local-api-docs`, `open-docusaurus-docs`

## Related

- [authentication.md](authentication.md) — trust table
- `electron/CONTEXT.md` — Local API vocabulary
- `docs-site/CONTEXT.md` — documentation bundle

## Changelog

| Date | Change |
|------|--------|
| 2026-07-05 | Initial Local API route catalog |