feat(api): add tiered per-endpoint rate limits (sync vs async vs poll)

app/api/limiter.py

@@ -2,13 +2,23 @@ from slowapi import Limiter
 from slowapi.util import get_remote_address
 from starlette.requests import Request
 
+# Tier definitions — referenced by name in route decorators
+# Sync analyze:  expensive full pipeline, strict limit
+# Async submit:  just queues a Celery task, more generous
+# Job poll:      read-only status check, very generous
+# Health/metrics: unrestricted (no decorator applied)
+
+LIMIT_SYNC_ANALYZE  = "5/minute"
+LIMIT_ASYNC_SUBMIT  = "20/minute"
+LIMIT_JOB_POLL     = "120/minute"
+
 
 def get_rate_limit_key(request: Request) -> str:
-    """Rate limit by API key if present, fall back to IP."""
+    """Rate limit by API key if present, fall back to IP address."""
     api_key = request.headers.get("X-API-Key")
     if api_key:
         return f"key:{api_key}"
     return f"ip:{get_remote_address(request)}"
 
 
-limiter = Limiter(key_func=get_rate_limit_key)
+limiter = Limiter(key_func=get_rate_limit_key)

app/api/routes.py

@@ -15,6 +15,8 @@ from app.services.analysis_service import run_full_analysis
 from app.agents import repo_analysis_agent
 from app.models.review import ReviewFeedback
 from app.tools.github_tool import clone_repository, delete_repository
+from app.api.limiter import limiter, LIMIT_SYNC_ANALYZE, LIMIT_ASYNC_SUBMIT, LIMIT_JOB_POLL
+
 
 router = APIRouter()
 
@@ -29,7 +31,7 @@ def health_check() -> dict[str, str]:
 @router.post(
     "/analyze", response_model=EngineeringReport, dependencies=[Depends(verify_api_key)]
 )
-@limiter.limit("5/minute")
+@limiter.limit(LIMIT_SYNC_ANALYZE)
 async def analyze_repository(
     request: Request, body: RepositoryRequest
 ) -> EngineeringReport:
@@ -57,7 +59,7 @@ async def analyze_repository(
     status_code=202,
     dependencies=[Depends(verify_api_key)],
 )
-@limiter.limit("5/minute")
+@limiter.limit(LIMIT_ASYNC_SUBMIT)
 async def analyze_repository_async(
     request: Request, body: RepositoryRequest
 ) -> JobSubmitResponse:
@@ -74,6 +76,7 @@ async def analyze_repository_async(
     response_model=JobStatusResponse,
     dependencies=[Depends(verify_api_key)],
 )
+@limiter.limit(LIMIT_JOB_POLL)
 def get_job_status(job_id: str) -> JobStatusResponse:
     """Poll the status/result of an async analysis job."""
     result = celery_app.AsyncResult(job_id)

docs/api.md

@@ -48,4 +48,20 @@ Request:
 Response: `RepositoryResponse` object
 
 ## Interactive Docs
-Visit http://localhost:8000/docs for Swagger UI
+Visit http://localhost:8000/docs for Swagger UI
+
+## Rate limits
+
+All limits are applied per API key (via `X-API-Key` header). Requests without
+a key are limited by IP address.
+
+| Endpoint | Limit | Reason |
+|---|---|---|
+| `POST /api/v1/analyze` | 5 req/min | Full pipeline — LLM calls, clone, static analysis |
+| `POST /api/v1/analyze/async` | 20 req/min | Queue submission only — fast and cheap |
+| `GET /api/v1/jobs/{id}` | 120 req/min | Read-only status poll |
+| `GET /api/v1/health` | unlimited | Healthcheck — no limit applied |
+| `GET /metrics/prometheus` | unlimited | Prometheus scrape — no limit applied |
+
+When a limit is exceeded the API returns `429 Too Many Requests` with a
+`Retry-After` header indicating when the client may retry.