API overview

Base URL, authentication, health check, and onboarding endpoints.

Base URL: http://localhost:8000/api/v1

All endpoints require authentication when ORION_AUTH_DISABLED is not set. Pass an Authorization: Bearer <token> header.

REST vs MCP: The REST API and MCP tools share the same service layer. Use MCP for agent-to-Orion communication (16 tools, optimized for AI workflows). Use REST for human-facing applications, admin operations, and integrations that don't speak MCP.

Authentication

POST /auth/register

Create a user account. Returns a session token. In MVP mode, the first user becomes the Galaxy owner.

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "andy@example.com", "password": "secret", "name": "Andy"}'

{"token": "eyJ...", "user_id": "u-123", "email": "andy@example.com", "name": "Andy", "role": "owner"}

POST /auth/login

Authenticate and receive a session token (7-day expiry).

POST /auth/logout

Invalidate the current session token.

GET /auth/me

Current user's profile, role, and Galaxy assignment.

Health

GET /health

No auth required. Returns service status and any degraded dependencies.

{"status": "ok", "service": "orion-api", "version": "0.1.0", "degraded": []}

degraded lists unavailable services: redis, chroma, ollama. The API continues to function with degraded services — Redis misses fall through to ChromaDB, and Ollama failures disable LLM-powered features while keeping core storage and retrieval operational.

Onboarding

POST /onboarding/start

Create a Galaxy with the 6-step onboarding wizard. See the Quickstart for the full request body and response.

POST /onboarding/import

Import markdown files into a planet. Query params: planet_id (required), path (required — local filesystem path).