securelens-backend/docs/api-reference.md

API Reference — SecureLens Backend

All endpoints run at http://localhost:8000 in development.

Interactive documentation (Swagger UI) is available at http://localhost:8000/docs.

---

Authentication

SecureLens uses JWT Bearer tokens for authentication. After registering or logging in, you get a token. Pass it in the Authorization header for any protected endpoint:

Authorization: Bearer <your_token>

Tokens are valid for 24 hours by default (configurable via JWT_EXPIRY_MINUTES in .env).

---

Endpoints

Health & Status

GET /

Returns a simple welcome message. Used to verify the server is up.

Response:

{ "message": "SecureLens AI Backend is running" }

GET /health

Returns server health status and version info.

Response:

{
  "status": "healthy",
  "version": "1.0.0"
}

---

Authentication

POST /auth/register

Creates a new account and returns a JWT token immediately (no separate login needed).

Request Body:

{
  "email": "user@example.com",
  "username": "myuser",
  "password": "securepassword123"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "token_type": "bearer"
}

Errors:

• 400 — Email or username already exists

---

POST /auth/login

Logs in with email and password, returns a JWT token.

Request Body:

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response: Same as register.

Errors:

• 401 — Invalid credentials

---

GET /auth/me

Returns info about the currently authenticated user. Requires a valid token.

Response:

{
  "id": "uuid",
  "email": "user@example.com",
  "username": "myuser",
  "created_at": "2026-04-25T10:00:00Z"
}

---

Website Scanner

POST /scan

Scans a live URL for infrastructure-level security vulnerabilities. Authentication is optional — if you're logged in, the scan is saved to your history.

Request Body:

{
  "url": "https://example.com"
}

Response:

{
  "url": "https://example.com",
  "score": 62,
  "grade": "C",
  "summary": "Found 8 security issues...",
  "issues": [
    {
      "layer": "Server Config",
      "issue": "Missing Content-Security-Policy header",
      "severity": "High",
      "explanation": "Without CSP, the browser cannot restrict...",
      "remediation_snippet": "add_header Content-Security-Policy \"default-src 'self'\";"
    }
  ],
  "threat_narrative": "An attacker could chain the missing CSP..."
}

The score is 0–100 (higher is better). The grade maps to:

Score	Grade
90–100	A
75–89	B
50–74	C
25–49	D
0–24	F

Errors:

• 400 — Invalid URL or URL validation failed (SSRF protection)
• 422 — Malformed request body

---

Scan History

All history endpoints require authentication.

GET /scans

Returns a list of all your past website scans.

Response:

[
  {
    "id": "uuid",
    "url": "https://example.com",
    "score": 62,
    "grade": "C",
    "created_at": "2026-04-25T10:00:00Z"
  }
]

---

GET /scans/{id}

Returns the full details of a specific scan by ID.

---

DELETE /scans/{id}

Deletes a scan from your history.

Response: 204 No Content

Errors:

• 404 — Scan not found or doesn't belong to your account

---

Code Scanner (AI Agent)

These endpoints power the GitHub repository scanner.

POST /code-scan/analyze

Triggers the full AI agent pipeline against a GitHub repository. This is the main endpoint.

What happens internally:

1. Fetches the complete file tree from GitHub
2. AI selects the 5 most security-critical files (Triage)
3. AI analyzes each file concurrently for OWASP Top 10 issues (Analysis)
4. AI writes an executive summary (Summary)
5. Results are stored in memory under the returned scan_id

Request Body:

{
  "repo_url": "https://github.com/username/repository",
  "github_token": "ghp_xxxxxxxxxxxx",
  "branch": "main"
}

• repo_url — Full GitHub repository URL
• github_token — A GitHub personal access token with repo read scope. Needed to access private repos and to avoid GitHub's anonymous rate limits.
• branch — Optional. Defaults to "main".

Response:

{
  "scan_id": "4432ad8e-4aa7-40bf-8f37-b0bbb96f6677",
  "repo_url": "https://github.com/username/repository",
  "summary": "The repository presents a moderate security risk...",
  "issues": [
    {
      "file_path": "app/users/page.js",
      "severity": "High",
      "issue": "Potential Broken Access Control on User List API",
      "explanation": "The client-side code fetches all users without authentication...",
      "suggested_fix": "Add auth middleware to the /users API endpoint...",
      "line_number": 12
    }
  ]
}

Save the scan_id — you need it to use the chat endpoint.

Errors:

• 500 — AI API error, GitHub API error, or invalid repo URL

---

POST /code-scan/chat

Opens a conversational interface with the AI, grounded in the context of a specific scan.

The AI knows exactly what vulnerabilities were found in which files. You can ask it to explain issues, write patches, prioritise fixes, or anything else security-related.

Request Body:

{
  "scan_id": "4432ad8e-4aa7-40bf-8f37-b0bbb96f6677",
  "message": "Can you write a patch for the highest severity issue you found?"
}

Response:

{
  "reply": "The highest severity issue was the Broken Access Control in app/users/page.js. Here's the fix...\n\n```javascript\n// Add this middleware to your API route\n..."
}

Errors:

• 404 — scan_id not found (scan expired or server restarted)
• 500 — AI API error

Note: Scan contexts are stored in memory and are lost when the server restarts. Always run a fresh /code-scan/analyze first when starting a new session.

---

GET /code-scan/models

Lists all Gemini models available to your API key. Useful for debugging model access issues.

Response:

{
  "models": [
    "models/gemini-2.0-flash",
    "models/gemini-2.5-flash",
    "models/gemini-2.5-pro"
  ]
}

---

Rate Limits

The API is rate-limited to 30 requests per minute by default (configurable via RATE_LIMIT in .env).

The Gemini AI calls are additionally subject to Google's API rate limits:

Model	Free Tier RPM	Free Tier RPD
gemini-2.0-flash	15	1,500
gemini-2.5-flash	10	~20

If you hit the Gemini rate limit, the API returns a 429 from Google which surfaces as a 500 from the SecureLens server. Wait 60 seconds and try again.

---

Error Codes

Code	Meaning
400	Bad request — check your input
401	Not authenticated — missing or expired token
403	Forbidden — you don't have permission for this resource
404	Resource not found
422	Validation error — malformed request body
429	Rate limited — slow down your requests
500	Server error — usually an AI API failure