[Docs] Create REST API Reference (docs/reference/API_REFERENCE.md) for repowise serve endpoints

[akshatmalik-bruh]

Problem Statement

While Repowise maintains dedicated reference documentation for the CLI (CLI_REFERENCE.md), configuration schema (CONFIG.md), and MCP tools (MCP_TOOLS.md) under docs/reference/, there is currently no REST API Reference document (API_REFERENCE.md).

The FastAPI backend (repowise serve) powers both the Next.js web dashboard and external HTTP clients, exposing 33 router modules under packages/server/src/repowise/server/routers/. While individual endpoints are mentioned in passing across architecture deep-dives, developers building custom integrations or querying repowise serve programmatically lack a single, authoritative API reference detailing request/response schemas, parameters, authentication, and status codes.

---

Undocumented Endpoint Clusters

Below is the breakdown of the 33 router modules that require OpenAPI / Markdown documentation:

1. Repository Management & Sync (routers/repos.py, routers/jobs.py)

• GET /api/repos — List registered repositories
• GET /api/repos/summary — Aggregate stats for all repositories in one call
• POST /api/repos — Register a new repository
• POST /api/repos/{id}/sync — Trigger structural graph sync (no LLM calls)
• POST /api/repos/{id}/full-resync — Full regeneration of wiki pages and vector embeddings
• GET /api/jobs & GET /api/jobs/{id}/stream — Background job status and live SSE progress stream

2. Workspace & Multi-Repo Architecture (routers/workspace.py, routers/coupling.py)

• GET /api/workspace/system-graph — System-wide cross-repo dependency graph
• GET /api/workspace/contracts & /detail — Extracted API contract links and schemas
• GET /api/workspace/blast-radius — Cross-repository blast radius analysis
• GET /api/workspace/breaking-changes — Incompatible cross-repo contract report
• GET /api/workspace/conformance — Architectural boundary conformance report
• GET /api/workspace/architecture — System score and role metrics per repo/service
• GET /api/workspace/diagnostics — Workspace health and drift diagnostics

3. Refactoring & Code Health (routers/refactoring.py, routers/code_health/)

• GET /api/repos/{id}/refactoring/opportunities — Ranked refactoring suggestions
• GET /api/repos/{id}/refactoring/opportunities/{opportunity_id} — Detailed refactoring plan
• POST /api/repos/{id}/refactoring/{suggestion_id}/generate-code — Generate refactored diff
• GET/PUT /api/repos/{id}/refactoring/settings — Toggle LLM refactoring settings
• GET /api/repos/{id}/health/overview — Defect, maintainability, and performance scores
• GET /api/repos/{id}/health/coverage — Coverage ingestion stats and per-file test coverage

4. Architecture Visualization & C4 (routers/c4.py)

• GET /api/graph/{id}/c4/l1 — L1 System Context diagram payload
• GET /api/graph/{id}/c4/l2 — L2 Container diagram payload
• GET /api/graph/{id}/c4/l3 — L3 Component diagram payload
• GET /api/graph/{id}/c4/structurizr — Structurizr DSL export
• GET /api/graph/{id}/c4/mermaid — Mermaid SVG/diagram export

5. Search, Symbols & Documentation (routers/search.py, routers/pages.py, routers/symbols.py)

• GET /api/search — Hybrid search (semantic vector + FTS5/tsvector full-text)
• GET /api/pages — Wiki page retrieval (supports fields=summary or fields=full)
• GET /api/symbols — Symbol index and filterable call graph

6. Architectural Decisions & Episodes (routers/decisions.py, routers/episodes.py)

• GET /api/repos/{id}/decisions — ADR list and candidates
• GET /api/repos/{id}/decisions/lane-counts — Decision counts by lifecycle lane
• GET /api/repos/{id}/episodes — Mined transcripts and decisions over HTTP

7. Codebase Chat (routers/chat.py)

• POST /api/repos/{id}/chat/messages — SSE streaming agentic Q&A loop
• GET/DELETE /api/repos/{id}/chat/conversations — Conversation history persistence

8. Webhooks & System Operations (routers/webhooks.py, routers/meta.py, routers/mcp.py)

• POST /api/webhooks/github — GitHub push webhook (HMAC verified)
• POST /api/webhooks/gitlab — GitLab push webhook
• GET/PATCH /api/mcp/tools — Read/toggle active MCP tool surface per repo
• GET /health & GET /metrics — Liveness/readiness probes and Prometheus metrics

---

Proposed Solution

1. Create docs/reference/API_REFERENCE.md structured by resource area:
   • Authentication (REPOWISE_API_KEY bearer token requirements)
   • Response envelope formats and error payload shapes
   • Endpoint reference tables (HTTP method, route, parameters, return type)
   • Code examples (curl / fetch)
2. Add a cross-link to API_REFERENCE.md in docs/README.md and docs/architecture/ARCHITECTURE.md.

---

Tasks

• Draft docs/reference/API_REFERENCE.md
• Document authentication headers and error responses
• Document all 33 router endpoint groups
• Cross-link from main documentation navigation

[RaghavChamadiya]

Thanks @akshatmalik-bruh. The gap is real: someone querying repowise serve programmatically has nowhere to start, and the router count is right, there are 33 modules under server/routers/.

I want to push back on the shape before you spend more time on #2094, because I think most of what is proposed already exists and the part that does not is the part worth writing.

The endpoint reference is already generated and already served. app.py:461-466 constructs the app with FastAPI's defaults and nothing anywhere in packages/server/ sets docs_url or openapi_url:

app = FastAPI(
    title="repowise API",
    description="REST API for repowise — codebase documentation engine",
    version=__version__,
    lifespan=lifespan,
)

So repowise serve already publishes /openapi.json and a Swagger UI at /docs, derived from the route signatures and the Pydantic response models. Methods, routes, parameters, request and response schemas and status codes are all in there and cannot drift, because they are the code.

A hand-maintained markdown table covering the same 33 groups drifts the first time someone adds a query parameter, and it drifts silently, since nothing tests prose against routes. Stale API docs are worse than no API docs: they are believed. That is the version of this I do not want to take on.

What OpenAPI does not carry is worth a document, and it is the useful half of your outline:

• Authentication. The REPOWISE_API_KEY bearer requirement, which endpoints enforce it, and what happens when it is absent.
• The error payload shape and any response envelope conventions, stated once rather than inferred from a schema per route.
• Streaming semantics. GET /api/jobs/{id}/stream and the chat endpoint are SSE, and OpenAPI describes an SSE endpoint poorly. Event names, ordering, and how a client knows the stream ended belong in prose.
• Which endpoints spend money. This is the one I would put first. POST /api/repos/{id}/full-resync, the chat endpoint and refactoring/{id}/generate-code make model calls; the rest do not. Nothing in the OpenAPI schema says so, and it is the first thing anyone integrating needs to know.
• Conventions that repeat across routes, like fields=summary versus fields=full on /api/pages, documented once instead of thirteen times.
• A short orientation table, resource area to router, so a reader knows which part of /docs to open. Not an endpoint-by-endpoint duplicate.

That is a document that stays true, and it is considerably shorter to write than the four-task version in the issue.

One small correction for the issue text: MCP_TOOLS.md is not under docs/reference/, it lives at docs/agent/MCP_TOOLS.md. docs/reference/ currently holds CLI_REFERENCE.md, COMPUTED_GLOSSARY.md, CONFIG.md, TELEMETRY.md and UPGRADING.md.

Happy to take docs/reference/API_REFERENCE.md on the scope above, with the cross-links from docs/README.md you proposed. Labelling documentation.