Introduction

These are the HTTP endpoints exposed by the FastAPI app (./dev.sh). The running server also serves interactive Swagger UI at /docs and ReDoc at /redoc, both generated from /openapi.json.

Base URL

http://localhost:8000

The default local development server. Every path below is relative to this base.

Authentication

Every route below / requires a bearer token. Log in with POST /auth/login and send the returned token on every request:

Authorization: Bearer <token>

Requests without a valid token return 401. A role that can't perform an action returns 403. See Authentication for the full model.

Roles

Each endpoint below is tagged with the role it requires:

• public — no token needed.
• any — any authenticated role (admin, user or viewer).
• restricted — the pill shows exactly which roles (e.g. admin, user).

Typical flow

1. POST /auth/login — log in (default admin/admin on first boot).
2. POST /config/llm — configure the chat model (or set OLLAMA_CHAT_MODEL).
3. POST /instances/pipeline — ingest a repository. Returns a job_id.
4. GET /instances/jobs/{job_id} — poll until status = succeeded.
5. POST /chat — ask questions; the answer streams back over SSE.

Errors

Errors return a JSON body { "detail": "..." }. Validation failures (422) return FastAPI's structured detail array. When Postgres is unreachable, protected routes return 503 at the auth layer.