Skip to content

API.md

Latest commit

 

History

History
207 lines (155 loc) · 4.62 KB

API.md

File metadata and controls

207 lines (155 loc) · 4.62 KB
Raw

API Reference

Base URL: http://localhost:8000 (configurable via RAG_API_HOST / RAG_API_PORT). Interactive Swagger docs: http://localhost:8000/docs (auto-generated by FastAPI from backend/models/schemas.py).

GET /health

{ "status": "ok", "ollama_available": true }

POST /repos/upload

Multipart form upload of a .zip archive. Starts indexing as a background task and returns immediately with status: "pending".

Request: multipart/form-data, field file = the .zip

Response:

{ "repo_id": "4ee1aced6717", "status": "pending", "files_total": 0, "files_indexed": 0, "chunks_total": 0, "languages": [], "error": null }

POST /repos/index-local

Index a folder already on the server's filesystem (or an existing git checkout). Does not copy files — reads directly from the given path.

Request:

{ "local_path": "/home/user/projects/my-app", "repo_id": "my-app-optional" }

Response: same shape as /repos/upload.

GET /repos/{repo_id}/status

Poll during indexing for progress.

{
  "repo_id": "4ee1aced6717",
  "status": "indexing",
  "files_total": 340,
  "files_indexed": 210,
  "chunks_total": 0,
  "languages": [],
  "error": null
}

status transitions: pending → indexing → completed | failed.

GET /repos/{repo_id}/stats

{
  "repo_id": "4ee1aced6717",
  "files_indexed": 340,
  "total_chunks": 2891,
  "languages": { "python": 210, "javascript": 90, "sql": 40 },
  "total_loc": 48213
}

GET /repos

List every indexed repo (for the UI's repo picker).

[ { "repo_id": "4ee1aced6717", "status": "completed", "files_indexed": 340, "chunks_total": 2891, "created_at": "2026-07-18 10:00:00" } ]

POST /chat

The main Q&A endpoint. Retrieves relevant chunks, builds a grounded prompt, calls the local LLM.

Request:

{
  "repo_id": "4ee1aced6717",
  "question": "How does authentication work?",
  "conversation_id": null,
  "top_k": 8,
  "language_filter": null,
  "file_filter": null
}

Response:

{
  "conversation_id": "3653dbef-...",
  "answer": "Authentication is handled by AuthService.login() (SOURCE 1), which looks up the user via self.db.find_user() and checks the password hash with _check_password() (SOURCE 1)...",
  "citations": [
    {
      "file_path": "app/services/auth_service.py",
      "function_name": "login",
      "start_line": 9,
      "end_line": 12,
      "language": "python",
      "snippet": "def login(self, username, password):\n    ...",
      "score": 0.87
    }
  ],
  "warning": null
}

If retrieval finds nothing relevant, citations is [], warning explains why, and the LLM is never called (see README's anti-hallucination section).

Pass the returned conversation_id on the next request to continue the same conversation with memory of prior turns.

POST /search

Standalone metadata + vector search, no LLM call — powers the UI's Search tab.

Request:

{
  "repo_id": "4ee1aced6717",
  "query": "login",
  "top_k": 15,
  "language": "python",
  "chunk_type": "function",
  "file_path_contains": "auth"
}

Response: array of

{
  "chunk_id": "ebf9147f...",
  "file_path": "app/auth.py",
  "name": "login",
  "chunk_type": "function",
  "language": "python",
  "start_line": 1,
  "end_line": 3,
  "score": 0.95,
  "snippet": "def login(u, p):\n    ..."
}

GET /repos/{repo_id}/graph/mermaid

Import/dependency graph as Mermaid flowchart syntax.

{ "mermaid": "flowchart TD\n    n0[\"app/main.py\"]\n    n0 --> n1\n    n1[\"app/auth.py\"]", "edge_count": 1 }

GET /repos/{repo_id}/graph/classes

Class diagram (classes + their methods) as Mermaid classDiagram syntax.

GET /repos/{repo_id}/summary

Structural, non-LLM summary: language breakdown, top-level directories, most-imported files.

{
  "repo_id": "4ee1aced6717",
  "files_indexed": 340,
  "total_chunks": 2891,
  "total_loc": 48213,
  "languages": { "python": 210 },
  "top_level_directories": { "app": 300, "tests": 40 },
  "most_imported_files": [ { "file_path": "app/models/user.py", "imported_by_count": 12 } ]
}

GET /repos/{repo_id}/importers?symbol=AuthService

{ "symbol": "AuthService", "importers": ["app/main.py", "app/routes/auth_routes.py"] }

Error responses

  • 400 — bad input (invalid zip, missing local path, malformed request)
  • 404 — unknown repo_id
  • 200 with warning field set — LLM unreachable or no relevant context found (deliberately not an error status, since the request itself was valid and citations may still be useful)