API reference

Jarvis exposes a local HTTP API from the same backend that serves the web UI. The public contract is split into three layers:

REST endpoints for application state and operations
SSE streams for long-running responses and live updates
MCP JSON-RPC tools used by worker runtimes

This page covers the REST surface at a high level. SSE and MCP behavior are documented separately in SSE events and MCP worker tools.

Auth model

Jarvis is designed as a personal, local-first system. Authentication is API key based.

Generate a key with python scripts/generate_api_key.py -d "<device name>"
Send the key as a bearer token: Authorization: Bearer <your-key>
API keys are stored hashed in the local database
The raw key is shown only once at creation time

Most user-facing API requests are expected to come from a local browser session, the desktop shell, or a trusted personal integration. Do not expose a Jarvis instance directly to the public internet without an explicit remote-access layer in front of it.

Local endpoint shape

In local development and self-hosted single-user setups, Jarvis typically listens on:

http://127.0.0.1:8888

Worktree instances may use a different local port. Treat the backend as the single origin for both the UI and the API.

Common URL patterns:

/api/v1/...
/mcp

Representative REST route families confirmed in the backend source include:

chat and chat history
settings
runtime control
Session OS
workspaces
scheduled tasks
local task streams
remote tunnel and remote-access helpers
changelog and health endpoints

The exact endpoint list should be taken from generated schema output, not from this prose page.

Source of truth

Jarvis uses FastAPI on the backend. The long-term public reference model is:

Generate OpenAPI directly from the FastAPI application
Publish that generated schema as a versioned docs artifact
Keep hand-written reference pages only for protocol semantics that OpenAPI does not describe well

That means:

REST endpoint names, parameters, and response models belong in generated OpenAPI
SSE event semantics belong in hand-written docs
MCP tool behavior belongs in hand-written docs

OpenAPI generation plan

The docs-site scaffolding plan uses a generated schema artifact rather than a manually maintained endpoint table. In practice, the docs build is intended to:

export an OpenAPI JSON document from the FastAPI app
publish it with the static docs output
link this page to that versioned schema download

This keeps the published REST reference aligned with the running backend and avoids stale endpoint inventories in Markdown.

What this page intentionally does not do

This page does not attempt to enumerate every route by hand. Jarvis evolves quickly across chat, session orchestration, remote access, and local runtime management. A hand-written endpoint list would drift and become misleading.

Instead, use this page for:

auth expectations
base URL conventions
contract boundaries between REST, SSE, and MCP
understanding where generated schema fits into the docs system