Spaces:

varshithreddy1807
/

aria

Configuration error

App Files Files Community

aria / docs /API_REFERENCE.md

varshithreddy1807

feat: release Repository Intelligence Platform v1.0.0

8904f7b 3 months ago

preview code

Raw History Blame Contribute Delete

44.2 kB

API Reference

All endpoints are hosted at http://127.0.0.1:8001. Every route is also available under the /api/v1/ versioned prefix.

Authentication

When the application is configured with an API_KEY (via the environment variable), all expensive endpoints (indexing, ingestion, chat, issues, reports) require authentication.

You must supply the API key in one of the following HTTP headers:

X-API-Key Header:
```
X-API-Key: your_secret_api_key_here
```

Authorization Bearer Token Header:

Authorization: Bearer your_secret_api_key_here

Failed authentication requests return a 401 Unauthorized response:

{
  "detail": "Unauthorized. Invalid or missing API key."
}

Navigation

System Status & Utility
Repository Processing
Semantic Querying
Repository Chat (v2)
Architecture Intelligence
Interactive Graph Intelligence
Symbol Intelligence
Call Graph Intelligence
API Surface Intelligence
Git History & Churn
PR & Architecture Drift Intelligence
Dead Code Intelligence
Repository Intelligence Report
AI Engineering Advisor
Autonomous Engineering Agent (AEA²)
Intelligent IDE Workspace

System Status & Utility

GET /health

Returns the static configuration health — active LLM provider, model, embedding provider, and vector DB. This endpoint makes no external calls and is suitable for load balancer health probes.

Response (200 OK)

{
  "backend": "online",
  "llm_provider": "gemini",
  "llm_model": "gemini-2.5-flash",
  "embedding_provider": "BAAI/bge-small-en-v1.5",
  "vector_db": "chromadb",
  "status": "healthy"
}

GET /metrics

Returns application metrics in Prometheus text format. Exempt from rate limiting. Available at both /metrics and /api/v1/metrics.

Request Example

curl http://127.0.0.1:8001/metrics

Response (200 OK — `text/plain; version=0.0.4`)

# HELP http_requests_total Total number of HTTP requests.
# TYPE http_requests_total counter
http_requests_total{method="GET",path="/health",status="200"} 12.0

# HELP active_requests_count Total number of active requests.
# TYPE active_requests_count gauge
active_requests_count 0.0

# HELP build_duration_seconds Build pipeline durations in seconds.
# TYPE build_duration_seconds summary
build_duration_seconds_sum{repository="fastapi/fastapi"} 45.123
build_duration_seconds_count{repository="fastapi/fastapi"} 1

# HELP cache_hits_total Total number of analysis cache hits.
# TYPE cache_hits_total counter
cache_hits_total{cache_key="symbols"} 3.0

# HELP cache_size Total number of entries currently in the cache.
# TYPE cache_size gauge
cache_size 12.0

GET /api/repos/examples

Fetch a list of pre-configured example repositories designed for testing.

Request Example

curl http://127.0.0.1:8001/api/repos/examples

Response (200 OK)

[
  {
    "name": "google/guava",
    "url": "https://github.com/google/guava",
    "tech_stack": ["Java", "Maven"],
    "description": "Google core libraries for Java."
  },
  {
    "name": "fastapi/fastapi",
    "url": "https://github.com/fastapi/fastapi",
    "tech_stack": ["Python", "Pydantic", "Starlette"],
    "description": "High performance, easy to learn, fast to code, ready for production API framework."
  },
  {
    "name": "vercel/next.js",
    "url": "https://github.com/vercel/next.js",
    "tech_stack": ["JavaScript", "TypeScript", "React", "Rust"],
    "description": "The React Framework for the Web."
  }
]

GET /api/repos/recent

Fetch a list of repositories processed during the current server session, loaded from the persisted store.

Request Example

curl http://127.0.0.1:8001/api/repos/recent

Response (200 OK)

[
  {
    "name": "Ankita15k/GitNest",
    "url": "https://github.com/Ankita15k/GitNest",
    "tech_stack": ["JavaScript", "TypeScript"],
    "analyzed_at": "Just now"
  }
]

Repository Processing

POST /api/analyze (SSE Stream)

Trigger a full repository cloning, language parsing, code chunking, indexing, and architecture mapping pipeline. This endpoint streams real-time progress events using the text/event-stream mime-type.

Request Schema (AnalyzeRequest)

url (string, required): GitHub repository URL.
branch (string, optional): Git branch or ref. Defaults to "main".
model (string, optional): LLM model variant to use. Defaults to "deepseek-ai/deepseek-v4-flash".

{
  "url": "https://github.com/owner/repository",
  "branch": "main",
  "model": "deepseek-ai/deepseek-v4-flash"
}

Request Example

curl -N -X POST http://127.0.0.1:8001/api/analyze \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "url": "https://github.com/Ankita15k/GitNest",
    "branch": "main"
  }'

SSE Stream Events Progress Output

data: {"status": "cloning", "message": "Cloning repository from GitHub..."}
data: {"status": "cloned", "message": "✓ Repository cloned successfully"}
data: {"status": "detecting", "message": "Detecting languages and frameworks..."}
data: {"status": "detected", "message": "✓ Technologies detected: ['JavaScript', 'TypeScript']"}
data: {"status": "chunking", "message": "START: chunking"}
data: {"status": "chunking", "message": "END: chunking"}
data: {"status": "embedding", "message": "START: embeddings"}
data: {"status": "embedding", "message": "END: embeddings"}
data: {"status": "chroma", "message": "START: chroma indexing"}
data: {"status": "chroma", "message": "END: chroma indexing"}
data: {"status": "building_graph", "message": "Building file dependency graph..."}
data: {"status": "graph_built", "message": "✓ Dependency graph: 328 files parsed, 1440 edges", "files_parsed": 328, "dependencies_found": 1440, "entry_points": ["backend/src/index.js"]}
data: {"status": "analyzed", "message": "✓ Architecture analyzed"}
data: {"status": "complete", "message": "✓ Repository analysis complete!"}
data: {"status": "done", "repo": "Ankita15k/GitNest"}

POST /api/index

Clones, chunks, and indexes a repository's vector embeddings in ChromaDB, without building structural dependency graphs.

Request Schema (IndexRequest)

repo_url (string, required): GitHub repository URL.

{
  "repo_url": "https://github.com/owner/repository"
}

Response (200 OK)

{
  "status": "indexed",
  "files": 328,
  "chunks": 1549
}

GET /api/analysis/{owner}/{repo_name}

Fetch the complete metadata results of a repository analysis.

Response (200 OK)

{
  "analysis": {
    "structure": {
      ".": ["README.md", "package.json"],
      "src": ["app.js", "server.js"]
    },
    "dependencies": ["express", "cors", "jsonwebtoken"],
    "tech_stack": ["JavaScript", "TypeScript"],
    "metadata": {
      "owner": "Ankita15k",
      "name": "GitNest",
      "local_path": "C:\\Users\\Varshith Reddy\\.repo_intelligence\\cloned_repos\\Ankita15k_GitNest"
    }
  },
  "architecture": {
    "summary": "GitNest is a full-stack Git hosting dashboard built with Node.js and Express...",
    "reading_order": [
      "backend/src/index.js",
      "backend/src/app.js"
    ],
    "relationships": [
      {
        "source": "backend/src/index.js",
        "target": "backend/src/app.js",
        "relationship_type": "imports",
        "description": "Imports app instance to launch listener server."
      }
    ]
  }
}

Semantic Querying

POST /api/retrieve

Query the vector space index directly for a repository using BGE embeddings and generate a grounded LLM response.

Request Schema (RetrieveRequest)

repo (string, required): Repository identifier (owner/repo).
question (string, required): Question query.

{
  "repo": "owner/repository",
  "question": "How is authentication handled?"
}

Response (200 OK)

{
  "answer": "Authentication is implemented using JWT tokens inside authMiddleware.js...",
  "sources": [
    {
      "file": "backend/src/middleware/authMiddleware.js",
      "content": "const token = req.headers.authorization.split(' ')[1]; ...",
      "score": 0.92
    }
  ]
}

POST /api/chat (SSE Stream)

See Repository Chat (v2) → POST /api/chat for the full request/response specification including session_id, SSE event format, and streaming behavior.

POST /api/issues/map

See Repository Chat (v2) → POST /api/issues/map for the full request/response specification.

Architecture Intelligence

POST /api/architecture/build

Trigger Tree-sitter AST parsing over local cloned repository files and construct the dependency NetworkX graph.

Request Schema (ArchitectureBuildRequest)

repo (string, required): Repository identifier (owner/repo).

{
  "repo": "owner/repository"
}

Response (200 OK)

{
  "status": "built",
  "repo": "Ankita15k/GitNest",
  "files_parsed": 328,
  "dependencies_found": 1440,
  "entry_points": [
    "backend/src/index.js"
  ]
}

GET /api/architecture/{owner}/{repo_name}

Fetch the generated architecture summary, reading order, and relationship schemas.

Response (200 OK - ArchitectureSummary)

{
  "summary": "GitNest is a full-stack Git dashboard using Express and local git hooks...",
  "reading_order": [
    "backend/src/index.js",
    "backend/src/app.js"
  ],
  "relationships": [
    {
      "source": "backend/src/index.js",
      "target": "backend/src/app.js",
      "relationship_type": "imports",
      "description": "Instantiates app config schemas."
    }
  ]
}

GET /api/architecture/{owner}/{repo_name}/graph

Retrieve React Flow-compatible node and edge datasets for visualization.

Query Parameters

q (string, optional): Substring filter for file names/module paths.

Response (200 OK)

{
  "nodes": [
    {
      "id": "backend/src/index.js",
      "data": { "label": "index.js" },
      "position": { "x": 120, "y": 80 },
      "style": { "background": "#1e293b", "color": "#f8fafc" }
    }
  ],
  "edges": [
    {
      "id": "e_backend/src/index.js_backend/src/app.js",
      "source": "backend/src/index.js",
      "target": "backend/src/app.js",
      "animated": true
    }
  ]
}

POST /api/reading-order

Generate an optimal, ranked file list for onboarding new developers based on graph centrality metrics.

Request Schema (ReadingOrderRequest)

repo (string, required): Repository identifier (owner/repo).

{
  "repo": "owner/repository"
}

Response (200 OK - ReadingOrder)

{
  "repo": "Ankita15k/GitNest",
  "ordered_files": [
    {
      "rank": 1,
      "file_path": "backend/src/index.js",
      "reason": "Primary application entry point initializing server configurations.",
      "tier": "entry_point",
      "score": 150.0
    }
  ],
  "reasoning": [
    "Timeline starts with detected application entry points.",
    "Order prioritizes modules with high degree centrality scores."
  ],
  "estimated_reading_time": 45,
  "total_files_ranked": 328
}

POST /api/impact-analysis

Predict downstream affected modules and components resulting from a proposed change.

Request Schema (ImpactAnalysisRequest)

repo (string, required): Repository identifier (owner/repo).
issue (string, required): Change request or GitHub issue text.

{
  "repo": "Ankita15k/GitNest",
  "issue": "Add API key authentication"
}

Response (200 OK - ImpactAnalysis)

{
  "repo": "Ankita15k/GitNest",
  "issue_text": "Add API key authentication",
  "directly_affected_files": [
    "backend/src/middleware/authMiddleware.js"
  ],
  "indirectly_affected_files": [
    "backend/src/routes/auth.routes.js",
    "backend/src/app.js"
  ],
  "affected_components": [
    "Authentication",
    "API Layer"
  ],
  "risk_level": "medium",
  "estimated_file_count": 3,
  "dependency_paths": [
    {
      "path": [
        "backend/src/middleware/authMiddleware.js",
        "backend/src/routes/auth.routes.js",
        "backend/src/app.js"
      ]
    }
  ],
  "confidence": 85
}

Repository Chat (v2)

GET /api/chat/health

Live provider health diagnostic. Runs a health check against all configured LLM providers. Use for operational monitoring — not load balancer probes (has 200–400 ms latency due to live API calls).

Request Example

curl http://127.0.0.1:8001/api/chat/health

Response (200 OK)

{
  "status": "ok",
  "provider": "gemini",
  "api_key_present": true,
  "authenticated": true,
  "healthy": true,
  "latency_ms": 234.1,
  "error_type": null,
  "error_message": null,
  "recommendation": null,
  "circuit_states": [
    {"name": "gemini", "circuit_state": "CLOSED", "failure_count": 0}
  ],
  "all_providers": {
    "gemini": {
      "provider": "gemini",
      "model": "gemini-2.5-flash",
      "healthy": true,
      "authenticated": true,
      "latency_ms": 234.1,
      "error_type": null,
      "error_message": null,
      "recommendation": null
    }
  },
  "timestamp": 1750000000.0
}

status values: ok (all configured providers healthy), degraded (at least one healthy), unhealthy (none healthy), error (health check failed).

Status Codes

Code	Meaning
200	Health check ran — inspect `status` field for result
500	Health check itself failed unexpectedly

POST /api/chat/reload

Hot-reload the LLM provider without restarting the server. Call this after updating GEMINI_API_KEY or DEEPSEEK_API_KEY in .env. Resets the ProviderFactory cache, ProviderManager, and all circuit breakers, then verifies the new provider with a test call.

Request Example

curl -X POST http://127.0.0.1:8001/api/chat/reload

Response (200 OK)

{
  "status": "ok",
  "message": "LLM provider reloaded successfully. Chat is ready.",
  "test_response": "ready"
}

Error Response (500)

{
  "status": "error",
  "detail": "Provider loaded but test call failed: 401 UNAUTHENTICATED"
}

POST /api/chat

Interactive streaming chat over a repository's codebase context. Streams token-by-token via SSE.

The v2 pipeline runs: conversation memory → intent detection → intent routing → weighted retrieval (top-15 reranked to top-5) → context assembly → LLM streaming → memory update.

Request Schema (ChatRequest)

repo (string, required): Repository identifier (owner/repo)
message (string, required): User message
history (list, optional): Conversation history turns
session_id (string, optional): Session identifier for conversation memory. Defaults to "default"

{
  "repo": "fastapi/fastapi",
  "message": "How does dependency injection work?",
  "history": [
    {"role": "user", "content": "What is the entry point?"},
    {"role": "assistant", "content": "The entry point is fastapi/applications.py..."}
  ],
  "session_id": "user-abc-session-1"
}

SSE Stream Output

data: {"text": "FastAPI"}
data: {"text": "'s "}
data: {"text": "dependency "}
data: {"text": "injection "}
data: {"text": "uses "}
data: {"text": "the "}
data: {"text": "Depends() "}
data: {"text": "system..."}
data: {"sources": ["fastapi/dependencies/utils.py", "fastapi/routing.py"], "confidence": 91, "fallback_mode": false, "status": "done"}

The final SSE event always includes "status": "done".

Status Codes

Code	Meaning
200	SSE stream opened
400	`repo` field is empty
422	Request body validation failed

POST /api/issues/map

Map a GitHub issue to relevant source files and generate a grounded implementation plan. Uses exactly 2 LLM calls: one to parse the issue and rank files, one to generate the implementation plan. Results are cached by sha256(issue_text).

Request Schema (IssueMapRequest)

repo (string, required): Repository identifier (owner/repo)
title (string, optional): GitHub issue title
description (string, optional): GitHub issue body
issue (string, optional): Combined issue text (alternative to title + description)

{
  "repo": "fastapi/fastapi",
  "title": "Dependency injection fails with async generators",
  "description": "When using yield-based dependencies with async context managers, cleanup is not called."
}

Response (200 OK)

{
  "issue_summary": "Async generator dependencies do not trigger cleanup",
  "issue_type": "bug",
  "relevant_files": [
    "fastapi/dependencies/utils.py",
    "fastapi/concurrency.py"
  ],
  "affected_components": ["Services", "API Layer"],
  "implementation_plan": [
    {
      "step_number": 1,
      "description": "In fastapi/dependencies/utils.py, locate solve_dependencies() and ensure async generator cleanup is awaited.",
      "files_to_modify": ["fastapi/dependencies/utils.py"]
    }
  ],
  "complexity": "medium",
  "confidence": 84,
  "verified": true,
  "sources": ["fastapi/dependencies/utils.py", "fastapi/concurrency.py"]
}

Interactive Graph Intelligence

GET /api/graph/{owner}/{repo}/full

Retrieve the full dependency graph for visualization in the interactive layout.

Query Parameters

q (string, optional): Query substring to filter node files.

Request Example

curl http://127.0.0.1:8001/api/graph/VarshithReddy2006/Repo-Intelligence-Agent/full?q=service

Response (200 OK)

{
  "nodes": [
    {
      "id": "services/symbol_service.py",
      "label": "symbol_service.py",
      "category": "file",
      "language": "python"
    }
  ],
  "edges": [
    {
      "source": "services/symbol_service.py",
      "target": "models/symbol.py",
      "relationship": "imports"
    }
  ]
}

GET /api/graph/{owner}/{repo}/neighbors/{node_path:path}

Retrieve the immediate neighborhood of a single file node.

Request Example

curl http://127.0.0.1:8001/api/graph/VarshithReddy2006/Repo-Intelligence-Agent/neighbors/services/symbol_service.py

Response (200 OK)

{
  "nodes": [
    { "id": "services/symbol_service.py", "label": "symbol_service.py", "category": "focus", "language": "python" },
    { "id": "backend/api.py", "label": "api.py", "category": "predecessor", "language": "python" },
    { "id": "models/symbol.py", "label": "symbol.py", "category": "successor", "language": "python" }
  ],
  "edges": [
    { "source": "backend/api.py", "target": "services/symbol_service.py", "relationship": "imports" },
    { "source": "services/symbol_service.py", "target": "models/symbol.py", "relationship": "imports" }
  ]
}

GET /api/graph/{owner}/{repo}/trace/{node_path:path}

Trace all reachable nodes in the dependency graph starting from a node.

Query Parameters

direction (string, optional): Direction of walk. Options: forward, backward, both. Defaults to both.
depth (int, optional): BFS walk limit. Minimum 1, Maximum 12. Defaults to 6.

Request Example

curl "http://127.0.0.1:8001/api/graph/VarshithReddy2006/Repo-Intelligence-Agent/trace/services/symbol_service.py?direction=backward&depth=3"

Response (200 OK)

{
  "nodes": [
    { "id": "services/symbol_service.py", "label": "symbol_service.py", "category": "focus", "language": "python" },
    { "id": "backend/api.py", "label": "api.py", "category": "dependent", "language": "python" }
  ],
  "edges": [
    { "source": "backend/api.py", "target": "services/symbol_service.py", "relationship": "imports" }
  ]
}

GET /api/graph/{owner}/{repo}/search

Search for nodes by label or file path, returning matches highlighted with their immediate context.

Query Parameters

q (string, required): Query term.

Request Example

curl http://127.0.0.1:8001/api/graph/VarshithReddy2006/Repo-Intelligence-Agent/search?q=dead_code

Response (200 OK)

{
  "nodes": [
    { "id": "services/dead_code_service.py", "label": "dead_code_service.py", "category": "file", "language": "python", "highlighted": true },
    { "id": "backend/api.py", "label": "api.py", "category": "file", "language": "python", "highlighted": false }
  ],
  "edges": [
    { "source": "backend/api.py", "target": "services/dead_code_service.py", "relationship": "imports" }
  ]
}

Symbol Intelligence

GET /api/symbols/{owner}/{repo}/file/{file_path:path}

Retrieve all AST symbols (classes, functions, methods) defined in a file.

Request Example

curl http://127.0.0.1:8001/api/symbols/VarshithReddy2006/Repo-Intelligence-Agent/file/services/symbol_service.py

Response (200 OK)

{
  "file": "services/symbol_service.py",
  "repo": "VarshithReddy2006/Repo-Intelligence-Agent",
  "symbol_count": 2,
  "symbols": [
    {
      "name": "SymbolService",
      "type": "class",
      "file_path": "services/symbol_service.py",
      "line_number": 26,
      "language": "python",
      "parent_class": null
    },
    {
      "name": "get_file_symbols",
      "type": "function",
      "file_path": "services/symbol_service.py",
      "line_number": 95,
      "language": "python",
      "parent_class": "SymbolService"
    }
  ]
}

GET /api/symbols/{owner}/{repo}/definition/{symbol_name}

Find the definition site of a symbol.

Request Example

curl http://127.0.0.1:8001/api/symbols/VarshithReddy2006/Repo-Intelligence-Agent/definition/SymbolService

Response (200 OK)

{
  "symbol": "SymbolService",
  "repo": "VarshithReddy2006/Repo-Intelligence-Agent",
  "definition": {
    "name": "SymbolService",
    "type": "class",
    "file_path": "services/symbol_service.py",
    "line_number": 26,
    "language": "python",
    "parent_class": null
  }
}

GET /api/symbols/{owner}/{repo}/references/{symbol_name}

Search for references to a symbol across the repository symbol index.

Request Example

curl http://127.0.0.1:8001/api/symbols/VarshithReddy2006/Repo-Intelligence-Agent/references/SymbolService

Response (200 OK)

{
  "symbol": "SymbolService",
  "repo": "VarshithReddy2006/Repo-Intelligence-Agent",
  "references": [
    {
      "name": "SymbolService",
      "type": "class",
      "file_path": "services/symbol_service.py",
      "line_number": 26,
      "language": "python",
      "parent_class": null
    }
  ],
  "reference_count": 1,
  "note": "MVP: name-based matching only. Full cross-file call graph planned for PH2-003."
}

Call Graph Intelligence

POST /api/call-graph/build

Build the function-level call graph for a repository. Streams SSE progress. Requires the repository to have been analyzed (POST /api/analyze) and the symbol index to exist (POST /api/architecture/build).

Request Schema

repo (string, required): Repository identifier (owner/repo)

{"repo": "fastapi/fastapi"}

SSE Stream Events

data: {"status": "progress", "message": "Parsing function calls..."}
data: {"status": "result", "data": {"total_functions": 142, "total_edges": 389}}
data: {"status": "done"}

GET /api/call-graph/{owner}/{repo}

Return the call graph as React Flow JSON for visualization.

Query Parameters

q (string, optional): Filter by function name substring
max_nodes (int, optional): Maximum nodes to return. Range: 1–1000. Default: 300

Request Example

curl "http://127.0.0.1:8001/api/call-graph/fastapi/fastapi?q=router&max_nodes=50"

Response (200 OK)

{
  "nodes": [
    {"id": "fastapi.routing:APIRouter.add_api_route", "label": "add_api_route", "file": "fastapi/routing.py"}
  ],
  "edges": [
    {"source": "fastapi.routing:APIRouter.add_api_route", "target": "fastapi.routing:APIRoute.__init__"}
  ],
  "node_count": 1,
  "edge_count": 1
}

GET /api/call-graph/{owner}/{repo}/callers/{function_id}

Return all functions that directly call the given function.

Request Example

curl http://127.0.0.1:8001/api/call-graph/fastapi/fastapi/callers/fastapi.routing:APIRouter.add_api_route

Response (200 OK)

{
  "function_id": "fastapi.routing:APIRouter.add_api_route",
  "callers": [
    {"id": "fastapi.routing:APIRouter.get", "name": "get", "file": "fastapi/routing.py", "line": 412}
  ]
}

GET /api/call-graph/{owner}/{repo}/callees/{function_id}

Return all functions directly called by the given function.

GET /api/call-graph/{owner}/{repo}/hierarchy/{function_id}

Return the call hierarchy tree for a function (callers tree or callees tree).

Query Parameters

direction (string, optional): down (callees) or up (callers). Default: down
depth (int, optional): BFS depth limit. Range: 1–12. Default: 6

GET /api/call-graph/{owner}/{repo}/blast-radius/{function_id}

Return the function-level blast radius — all functions reachable from this one, with risk scoring.

GET /api/call-graph/{owner}/{repo}/stats

Return aggregate call graph statistics (total functions, total edges, most-called functions, most-calling functions).

GET /api/call-graph/{owner}/{repo}/neighbors/{function_id}

Return immediate callers and callees of a function as React Flow JSON.

GET /api/call-graph/{owner}/{repo}/trace/{function_id}

BFS trace from a function as React Flow JSON.

Query Parameters

direction (string, optional): forward, backward, or both. Default: both
depth (int, optional): BFS depth limit. Range: 1–12. Default: 6

API Surface Intelligence

POST /api/api-surface/build

Build the API surface index — classifies every exported symbol as public, internal, or deprecated, and computes Martin's instability metrics. Streams SSE progress. Requires analyzed repository and symbol index.

Request Schema

repo (string, required): Repository identifier (owner/repo)

{"repo": "fastapi/fastapi"}

SSE Stream Events

data: {"status": "progress", "message": "Classifying symbols..."}
data: {"status": "result", "data": {"total_symbols": 142, "public": 42, "internal": 98, "deprecated": 2}}
data: {"status": "done"}

GET /api/api-surface/{owner}/{repo}

Return the full API surface report including all symbols, stability metrics, and visibility ratio.

Request Example

curl http://127.0.0.1:8001/api/api-surface/fastapi/fastapi

GET /api/api-surface/{owner}/{repo}/stats

Return aggregate API surface statistics.

Response (200 OK)

{
  "total_symbols": 142,
  "public_count": 42,
  "internal_count": 98,
  "deprecated_count": 2,
  "visibility_ratio": 0.296
}

GET /api/api-surface/{owner}/{repo}/public

Return all public symbols. Supports optional q search and kind filter query parameters, and a limit (default 100, max 1000).

GET /api/api-surface/{owner}/{repo}/internal

Return all internal symbols. Supports limit query parameter.

GET /api/api-surface/{owner}/{repo}/deprecated

Return all deprecated symbols.

GET /api/api-surface/{owner}/{repo}/breaking

Detect breaking changes between two API surfaces, or return orphaned public APIs if compare_repo is omitted.

Query Parameters

compare_repo (string, optional): Baseline repository identifier (owner/repo) to diff against

Response (200 OK — with compare_repo)

{
  "breaking_changes": [
    {
      "symbol": "authenticate_user",
      "type": "function",
      "change_type": "removed",
      "file_path": "services/auth_service.py"
    }
  ],
  "count": 1
}

Response (200 OK — without compare_repo)

{
  "orphans": [
    {
      "name": "legacy_helper",
      "type": "function",
      "file_path": "services/legacy_helper.py",
      "visibility": "public"
    }
  ],
  "count": 1
}

GET /api/api-surface/{owner}/{repo}/{symbol_name}

Return classification details for a single symbol by name.

Git History & Churn

POST /api/churn/analyze

Mine git commit history and compute per-file churn scores. Streams SSE progress.

Request Schema

repo (string, required): Repository identifier (owner/repo)
since_days (int, optional): Days of history to mine. Range: 7–3650. Default: 365

{
  "repo": "fastapi/fastapi",
  "since_days": 365
}

SSE Stream Events

data: {"status": "progress", "message": "Processing 1200 commits..."}
data: {"status": "result", "data": {"total_commits": 1200, "files_analyzed": 89}}
data: {"status": "done"}

GET /api/churn/{owner}/{repo}

Return the full churn summary. Requires POST /api/churn/analyze to have been run first.

Query Parameters

since_days (int, optional): Must match the value used during analysis. Default: 365

Response (200 OK)

{
  "repo": "fastapi/fastapi",
  "since_days": 365,
  "total_commits": 1200,
  "files_analyzed": 89,
  "top_churned_files": [
    {"file_path": "fastapi/routing.py", "commit_count": 87, "churn_score": 0.94}
  ],
  "timeline": [...]
}

GET /api/churn/{owner}/{repo}/hotspots

Return the top-N hotspot files (high churn × high graph centrality).

Query Parameters

since_days (int, optional): Default: 365
top_n (int, optional): Range: 1–100. Default: 25

Response (200 OK)

{
  "hotspots": [
    {
      "file_path": "fastapi/routing.py",
      "churn_score": 0.94,
      "centrality_score": 0.87,
      "hotspot_score": 0.91,
      "commit_count": 87,
      "risk_level": "HIGH"
    }
  ]
}

GET /api/churn/{owner}/{repo}/file/{file_path}

Return churn data for a single file.

Request Example

curl http://127.0.0.1:8001/api/churn/fastapi/fastapi/file/fastapi/routing.py

GET /api/churn/{owner}/{repo}/timeline

Return the weekly commit activity timeline.

Response (200 OK)

{
  "timeline": [
    {"week": "2026-01-06", "commit_count": 12},
    {"week": "2026-01-13", "commit_count": 8}
  ]
}

PR & Architecture Drift Intelligence

POST /api/pr/analyze

Perform risk assessment, changed files extraction, symbol diffs, and blast radius propagation for a Pull Request.

Request Schema (PRAnalyzeRequest)

owner (string, required): GitHub repository owner.
repo (string, required): GitHub repository name.
pr_number (int, required): GitHub pull request ID.

{
  "owner": "VarshithReddy2006",
  "repo": "Repo-Intelligence-Agent",
  "pr_number": 2
}

Response (200 OK)

{
  "repo": "VarshithReddy2006/Repo-Intelligence-Agent",
  "pr_number": 2,
  "risk_score": 24.5,
  "pr_size": "M",
  "blast_radius": "MEDIUM",
  "changed_files": [
    {
      "filename": "services/pr_intelligence_service.py",
      "status": "modified",
      "additions": 45,
      "deletions": 10,
      "changes": 55
    }
  ],
  "added_symbols": [],
  "modified_symbols": [
    {
      "name": "analyze_pull_request",
      "type": "function",
      "file_path": "services/pr_intelligence_service.py",
      "line_number": 85,
      "language": "python",
      "change_type": "modified",
      "parent_class": "PRIntelligenceService"
    }
  ],
  "removed_symbols": [],
  "affected_files": [
    "backend/api.py"
  ],
  "propagation_paths": [
    {
      "source": "services/pr_intelligence_service.py",
      "target": "backend/api.py",
      "path": ["backend/api.py", "services/pr_intelligence_service.py"],
      "depth": 1
    }
  ],
  "risk_breakdown": {
    "size_risk": "MEDIUM",
    "blast_radius_risk": "LOW",
    "drift_risk": "LOW",
    "hotspot_risk": "HIGH"
  },
  "review_focus_areas": [
    {
      "area": "hotspots",
      "description": "Changes to services/pr_intelligence_service.py modify highly coupled module logic.",
      "severity": "HIGH"
    }
  ],
  "analyzed_at": "2026-06-20T14:14:00Z"
}

GET /api/pr/health

Health diagnostics check for PR Intelligence configurations.

Query Parameters

owner (string, optional): GitHub owner.
repo (string, optional): GitHub repo.

Request Example

curl "http://127.0.0.1:8001/api/pr/health?owner=VarshithReddy2006&repo=Repo-Intelligence-Agent"

Response (200 OK)

{
  "github_token": true,
  "github_token_loaded": true,
  "github_token_prefix": "github_pat_1...",
  "github_rate_limit_authenticated": true,
  "rate_limit_remaining": 4982,
  "analysis_exists": true,
  "graph_available": true,
  "symbol_index_available": true,
  "status": "healthy"
}

POST /api/repos/repair

Repair a repository by forcefully regenerating its missing graph and symbol indices.

Request Schema

owner (string, required): GitHub owner.
repo (string, required): GitHub repo.

{
  "owner": "VarshithReddy2006",
  "repo": "Repo-Intelligence-Agent"
}

Response (200 OK)

{
  "status": "success",
  "message": "Repository indexes rebuilt successfully for 'VarshithReddy2006/Repo-Intelligence-Agent'",
  "details": {
    "architecture": { "status": "built", "repo": "VarshithReddy2006/Repo-Intelligence-Agent", "files_parsed": 34, "dependencies_found": 80 },
    "symbols": { "repo": "VarshithReddy2006/Repo-Intelligence-Agent", "symbols_parsed": 122 }
  }
}

POST /api/architecture/drift

Detect architectural drift, cycle additions, and coupling shifts introduced by a Pull Request.

Request Schema (PRDriftRequest)

owner (string, required): GitHub owner.
repo (string, required): GitHub repo.
pr_number (int, required): GitHub PR ID.

{
  "owner": "VarshithReddy2006",
  "repo": "Repo-Intelligence-Agent",
  "pr_number": 2
}

Response (200 OK)

{
  "repo": "VarshithReddy2006/Repo-Intelligence-Agent",
  "pr_number": 2,
  "added_dependencies": [],
  "removed_dependencies": [],
  "new_cycles": [],
  "resolved_cycles": [],
  "coupling_increase": [
    { "file": "services/pr_intelligence_service.py", "before": 4, "after": 5 }
  ],
  "coupling_decrease": [],
  "new_entry_points": [],
  "removed_entry_points": [],
  "architectural_hotspots": [
    "services/pr_intelligence_service.py"
  ],
  "risk_score": 10.0,
  "improvement_score": 0.0,
  "analyzed_at": "2026-06-20T14:14:00Z"
}

Dead Code Intelligence

POST /api/dead-code/analyze

Traces reachability from application entry points to sweep unreachable files, orphaned modules, and dead dependency chains.

Request Schema (DeadCodeRequest)

owner (string, required): GitHub owner.
repo (string, required): GitHub repo.

{
  "owner": "VarshithReddy2006",
  "repo": "Repo-Intelligence-Agent"
}

Response (200 OK)

{
  "repo": "VarshithReddy2006/Repo-Intelligence-Agent",
  "cleanup_score": 92,
  "previous_cleanup_score": null,
  "estimated_cleanup_effort": "LOW",
  "unused_files": [
    {
      "file_path": "scripts/unused_script.py",
      "confidence": 0.95,
      "risk_level": "SAFE",
      "recommendation": "Consider removing unused file scripts/unused_script.py"
    }
  ],
  "orphan_modules": [
    {
      "file_path": "services/legacy_helper.py",
      "confidence": 0.90,
      "risk_level": "REVIEW",
      "recommendation": "Review orphaned module services/legacy_helper.py; no active execution path reaches it.",
      "last_reachable_parent": "services/architecture_service.py"
    }
  ],
  "dead_dependency_chains": [
    {
      "chain": ["services/dead_chain_a.py", "services/dead_chain_b.py"],
      "confidence": 0.95,
      "risk_level": "SAFE",
      "recommendation": "Dependency chain [dead_chain_a.py -> dead_chain_b.py] appears unreachable and may be removable as a unit.",
      "length": 1,
      "total_nodes": 2,
      "max_centrality": 0.012
    }
  ],
  "cleanup_recommendations": [
    "Remove unused file scripts/unused_script.py (no active imports).",
    "Review orphaned module services/legacy_helper.py (previously connected via services/architecture_service.py)."
  ],
  "analyzed_at": "2026-06-20T14:14:00Z"
}

Repository Intelligence Report

POST /api/v1/report/{owner}/{repo}/build

Triggers the full scoring, rating, and serialization pipeline for a repository. Compiles raw analyses (circular dependencies, stability index, dead code, change risks) and persists the result to SQLite before returning the model.

Response (200 OK)

{
  "scores": {
    "overall": 87.5,
    "grade": "B",
    "breakdown": {
      "stability": 92.0,
      "api_distance": 85.0,
      "hygiene": 95.0,
      "churn": 80.0,
      "onboarding": 88.0
    }
  },
  "architecture": {
    "circular_dependencies": [
      ["services/a.py", "services/b.py", "services/a.py"]
    ],
    "coupling_hotspots": ["services/pr_intelligence_service.py"],
    "design_smells": [
      {
        "type": "HIGH_COUPLING",
        "file_path": "services/pr_intelligence_service.py",
        "description": "File has high in-degree / out-degree ratio."
      }
    ]
  },
  "api_surface": {
    "total_symbols": 142,
    "exported_symbols": 42,
    "visibility_ratio": 0.295,
    "instability_metrics": [
      {
        "module": "services/github_service",
        "efferent_coupling": 2,
        "afferent_coupling": 8,
        "instability": 0.20
      }
    ]
  },
  "hygiene": {
    "dead_functions": 12,
    "unreachable_files_count": 2,
    "registry": [
      {
        "symbol": "legacy_cleanup",
        "file_path": "services/legacy_helper.py",
        "line": 42
      }
    ]
  },
  "onboarding": {
    "entry_points": ["backend/api.py", "backend/cli.py"],
    "reading_path": [
      "models/report.py",
      "services/report/composer.py",
      "backend/routers/report.py"
    ]
  },
  "metadata": {
    "repo_name": "VarshithReddy2006/Repo-Intelligence-Agent",
    "commit_hash": "a8f4c2e",
    "generated_at": "2026-06-23T04:00:00Z"
  }
}

GET /api/v1/report/{owner}/{repo}/summary

Retrieves the overall health rating and score summary from the cache without running a full re-build.

Response (200 OK)

{
  "repo_name": "VarshithReddy2006/Repo-Intelligence-Agent",
  "score": 87.5,
  "grade": "B",
  "analyzed_at": "2026-06-23T04:00:00Z"
}

GET /api/v1/report/{owner}/{repo}/download

Downloads the formatted report in the requested file type.

Query Parameters

format (string, optional): One of html (default), pdf, or markdown.

Response (200 OK)

Binary Stream with appropriate MIME type (text/html or text/markdown) and Content-Disposition attachment header.

AI Engineering Advisor

POST /api/v1/repositories/{owner}/{repo}/advisor

Runs the full AI Engineering Advisor pipeline and returns a structured AdvisorReport. Consolidates information from the Repository Inspector, Engineering Memory, and Continuous Monitoring.

Response (200 OK)

{
  "repository": "fastapi/fastapi",
  "overall_priority": "medium",
  "total_recommendations": 12,
  "top_recommendations": [
    {
      "id": "rec-1",
      "title": "Resolve cycle between main and routing",
      "category": "architecture",
      "priority": "high",
      "estimated_effort": "medium"
    }
  ],
  "roadmap_phases": 3,
  "roadmap_summary": [
    {
      "phase": 1,
      "title": "Mitigate Security & Dependency Issues",
      "recommendation_count": 4
    }
  ]
}

GET /api/v1/repositories/{owner}/{repo}/advisor/latest

Returns the most recently persisted AdvisorReport.

Response (200 OK)

(Same schema format as Advisor Report)

GET /api/v1/repositories/{owner}/{repo}/advisor/recommendations

Returns the prioritized recommendation list from the latest AdvisorReport.

Query Parameters

priority (string, optional): Filter by: critical | high | medium | low.
category (string, optional): Filter by category name.
limit (int, optional): Maximum number to return (default 50).

Response (200 OK)

[
  {
    "id": "rec-1",
    "title": "Resolve cycle between main and routing",
    "category": "architecture",
    "priority": "high",
    "estimated_effort": "medium"
  }
]

GET /api/v1/repositories/{owner}/{repo}/advisor/roadmap

Returns the phased engineering roadmap from the latest AdvisorReport.

Response (200 OK)

[
  {
    "phase": 1,
    "title": "Mitigate Security & Dependency Issues",
    "recommendation_count": 4
  }
]

Autonomous Engineering Agent (AEA²)

POST /api/v1/repositories/{owner}/{repo}/execution-plan

Generates a structured implementation plan from the latest AdvisorReport. Requires a previously generated AdvisorReport to exist.

Response (200 OK)

{
  "repository": "fastapi/fastapi",
  "total_tasks": 8,
  "total_batches": 2,
  "critical_path_length": 5,
  "rollback_checkpoints": 2,
  "conflict_count": 0,
  "overall_risk": "low",
  "batches": [
    {
      "batch_id": "batch-1",
      "order": 1,
      "title": "Initial Refactoring Pass",
      "task_count": 3,
      "parallel": true,
      "estimated_effort": "1 day"
    }
  ],
  "critical_path": ["task-1", "task-3"],
  "metadata": {}
}

GET /api/v1/repositories/{owner}/{repo}/execution-plan/latest

Returns the most recently persisted ExecutionPlan.

Response (200 OK)

(Same schema format as ExecutionPlan)

GET /api/v1/repositories/{owner}/{repo}/execution-plan/batches

Returns the ordered execution batches from the latest ExecutionPlan.

Response (200 OK)

(Returns batches summary array)

GET /api/v1/repositories/{owner}/{repo}/execution-plan/critical-path

Returns the critical path of execution tasks.

Response (200 OK)

["task-1", "task-3"]

Intelligent IDE Workspace

GET /api/v1/repositories/{owner}/{repo}/workspace

Returns the complete consolidated IDE workspace snapshot for a repository.

Query Parameters

file (string, optional): Currently open file path.
symbol (string, optional): Currently selected symbol.
panel (string, optional): Active workspace panel name (default overview).

Response (200 OK)

{
  "state": {
    "repository": "fastapi/fastapi",
    "selected_file": "main.py",
    "selected_symbol": "app",
    "active_panel": "overview",
    "filters": {},
    "ui_preferences": {}
  },
  "overview": {
    "repository": "fastapi/fastapi",
    "description": "High performance API framework",
    "primary_language": "Python",
    "languages": ["Python"],
    "total_files": 342,
    "total_symbols": 1821,
    "architecture_style": "FastAPI Router Structure",
    "dependency_count": 12,
    "health": {
      "overall_score": 88,
      "overall_priority": "medium",
      "critical_count": 0,
      "high_count": 2,
      "medium_count": 4,
      "low_count": 6,
      "trend_direction": "stable"
    },
    "last_indexed_at": 1719543600,
    "metadata": {}
  },
  "explorer": null,
  "chat": null,
  "findings": null,
  "timeline": null,
  "monitor": null,
  "advisor": null,
  "execution": null,
  "available_panels": ["overview", "explorer", "chat", "findings", "timeline", "monitor", "advisor", "execution"],
  "metadata": {}
}

GET /api/v1/repositories/{owner}/{repo}/workspace/{panel}

Fetches details for a specific dashboard panel in the workspace. Available panels: overview, explorer, chat, findings, timeline, monitor, advisor, execution. Prefixes can be root /repositories/..., /api/repositories/..., or /api/v1/repositories/....

API Reference

Authentication

Navigation

System Status & Utility

GET /health

Response (200 OK)

GET /metrics

Request Example

Response (200 OK — text/plain; version=0.0.4)

GET /api/repos/examples

Request Example

Response (200 OK)

GET /api/repos/recent

Request Example

Response (200 OK)

Repository Processing

POST /api/analyze (SSE Stream)

Request Schema (AnalyzeRequest)

Request Example

SSE Stream Events Progress Output

POST /api/index

Request Schema (IndexRequest)

Response (200 OK)

GET /api/analysis/{owner}/{repo_name}

Response (200 OK)

Semantic Querying

POST /api/retrieve

Request Schema (RetrieveRequest)

Response (200 OK)

POST /api/chat (SSE Stream)

POST /api/issues/map

Architecture Intelligence

POST /api/architecture/build

Request Schema (ArchitectureBuildRequest)

Response (200 OK)

GET /api/architecture/{owner}/{repo_name}

Response (200 OK - ArchitectureSummary)

GET /api/architecture/{owner}/{repo_name}/graph

Query Parameters

Response (200 OK)

POST /api/reading-order

Request Schema (ReadingOrderRequest)

Response (200 OK - ReadingOrder)

POST /api/impact-analysis

Request Schema (ImpactAnalysisRequest)

Response (200 OK - ImpactAnalysis)

Repository Chat (v2)

GET /api/chat/health

Request Example

Response (200 OK)

Status Codes

POST /api/chat/reload

Request Example

Response (200 OK)

Error Response (500)

POST /api/chat

Request Schema (ChatRequest)

SSE Stream Output

Status Codes

POST /api/issues/map

Request Schema (IssueMapRequest)

Response (200 OK)

Interactive Graph Intelligence

GET /api/graph/{owner}/{repo}/full

Query Parameters

Request Example

Response (200 OK)

GET /api/graph/{owner}/{repo}/neighbors/{node_path:path}

Request Example

Response (200 OK)

GET /api/graph/{owner}/{repo}/trace/{node_path:path}

Query Parameters

Request Example

Response (200 OK)

GET /api/graph/{owner}/{repo}/search

Query Parameters

Request Example

Response (200 OK)

Symbol Intelligence

GET /api/symbols/{owner}/{repo}/file/{file_path:path}

Response (200 OK — `text/plain; version=0.0.4`)