API Reference

Base URL: http://localhost:8000

The API exposes interactive OpenAPI documentation out of the box. For the full endpoint list with schemas and try-it-out, run the stack and open:

• Swagger UI: http://localhost:8000/docs
• OpenAPI JSON: http://localhost:8000/openapi.json

This page covers what Swagger can't: auth flow, webhooks, and realtime.

Authentication

Single-user JWT auth. Data and mutation endpoints require a bearer token; /auth/*, /config, and /ws are exempt. In development without AUTH_PASSWORD, auth is bypassed; in production AUTH_PASSWORD is mandatory.

# Login (password from AUTH_PASSWORD in .env)
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "your-password"}'
# → { "access_token": "<jwt>", "token_type": "bearer" }

# Authenticated request
curl -H "Authorization: Bearer <jwt>" http://localhost:8000/notes/

GET /auth/status reports whether auth is configured.

Endpoint Groups

| Prefix | Area | |--------|------| | /notes | CRUD, semantic search (POST /notes/search/semantic), backlinks, similar notes, bulk ops, embedding retry | | /tags | Tags, tag co-occurrence graph, skill-tree parenting | | /skills | Skill tree | | /goals | Goals with failure modes (rollover, snowball, daily reset) | | /personal-streaks | Custom streaks | | /gamification | XP events, plant state | | /mood | Mood tracking | | /planning | Planning | | /folders | Vault folders | | /vault | Vault file operations | | /export | Data export | | /upload | File uploads | | /sync | Obsidian sync status, conflict resolution | | /ai | AI features (delegates to ai-service) | | /analytics, /stats, /metrics | Dashboards and metrics | | /integrations/github /integrations/google /integrations/strava /integrations/spotify | Third-party integrations (OAuth) | | /push | Web Push subscriptions (GET /push/vapid-public-key) | | /config | Runtime settings (exempt from JWT) | | /system/power | Host power/service management | | /webhook/obsidian | Inbound Obsidian events | | /ws | WebSocket realtime updates |

Obsidian Webhook

Bidirectional sync: the worker watches the vault filesystem, and Obsidian can push changes instantly via webhook (no polling).

POST /webhook/obsidian?secret=<OBSIDIAN_WEBHOOK_SECRET>

{
  "event": "create",
  "path": "/vault/My Note.md",
  "content": "---\ntitle: My Note\ntags: [python, web]\n---\n# Content here",
  "mtime": 1700000000
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | event | string | yes | create, update, or delete | | path | string | yes | File path (matches source_path in DB) | | content | string | create/update | Full file content (frontmatter + body) | | mtime | int | no | Remote modification time (Unix timestamp) |

Auth: if OBSIDIAN_WEBHOOK_SECRET is set, pass it as ?secret=. If unset but AUTH_PASSWORD is configured, JWT is required. If neither is set (dev mode), no auth.

POST /webhook/obsidian/legacy accepts the old payload format (note_id, path, remote_mtime) for backward compatibility.

WebSocket

WS /ws?token=<jwt>

Realtime updates for the frontend (note changes, XP events, sync status). Connections without a token are closed with code 4001.

Health & Metrics

• GET /health — API health check
• GET /metrics — Prometheus format (also on worker :8001)

Errors

Standard FastAPI error responses: 401 unauthorized, 404 not found, 422 validation errors with per-field detail.