securelens-backend/api_documentation.md

# SecureLens API Documentation (Frontend Integration Guide)

This document is designed to act as the primary blueprint for the `securelens-frontend` application. It details exactly how the frontend should communicate with the backend.

**Base URL**: `http://localhost:8000`

---

## 1. Authentication
SecureLens uses JWT Bearer tokens for UI authentication and API Keys for programmatic CI/CD usage. The frontend will rely exclusively on JWTs.

### `POST /auth/register`
- **Payload**: `{"email": "user@example.com", "username": "user", "password": "securepassword"}`
- **Response**: `{"id": "uuid", "email": "user@example.com", "username": "user"}`

### `POST /auth/login`
- **Content-Type**: `application/x-www-form-urlencoded`
- **Payload**: `username=user@example.com&password=securepassword`
- **Response**: `{"access_token": "ey...", "token_type": "bearer"}`
- **Action**: Store `access_token` in `localStorage` or secure cookie. Attach it as `Authorization: Bearer <token>` to all subsequent requests.

---

## 2. Dashboard Analytics
Used for populating the home page charts and historical views.

### `GET /scans/trends`
- **Auth Required**: Yes
- **Response**:
```json
{
  "total_scans": 12,
  "average_score": 85,
  "history": [
    {"url": "https://example.com", "score": 90, "date": "2023-10-27T..."},
    {"url": "https://staging.com", "score": 45, "date": "2023-10-26T..."}
  ]
}
```

---

## 3. The Scanning Engine
The core functionality of the product.

### `POST /scans/scan`
- **Auth Required**: Optional (If authenticated, saves to DB. If anonymous, returns ephemeral result).
- **Payload**: `{"url": "https://example.com"}`
- **Response**:
```json
{
  "id": "abc-123",
  "url": "https://example.com",
  "security_score": 85,
  "layers": {
    "Network": "Safe",
    "Headers": "Warning"
  },
  "issues": [
    {
      "issue": "Missing HTTPOnly on Session",
      "severity": "Critical",
      "layer": "Cookies",
      "fix": "Set HttpOnly flag to true",
      "contextual_severity": "High",
      "explanation": "Because you are using React, XSS could lead to cookie theft...",
      "remediation_snippet": "res.cookie('token', token, { httpOnly: true })"
    }
  ],
  "created_at": "2023-10-27T..."
}
```

---

## 4. AI Interfacing & Diagnostics
Views that trigger LLM behavior based on previous scans.

### `POST /scans/{scan_id}/chat`
- **Payload**: `{"message": "How do I fix the missing SPF record in AWS Route53?"}`
- **Response**: `{"reply": "To fix this in AWS..."}`

### `GET /scans/{scan_id}/threat-narrative`
- **Response**: `{"narrative": "An attacker could chain your missing CSP header with your exposed Git directory to..."}`

### `GET /scans/{old_id}/diff/{new_id}`
- **Response**: Returns lists of `resolved_issues`, `new_issues`, `persisting_issues`, and the integer `score_change`.

---

## 5. Webhooks & Exports
Settings and CI/CD generation views.

- **`GET /scans/{scan_id}/export/pdf`**: Triggers a browser file download of the PDF report.
- **`GET /scans/{scan_id}/export/csv`**: Triggers a CSV download.
- **`POST /webhooks`**: `{"target_url": "https://my-discord.com/hook"}`
- **`GET /webhooks`**: Returns a list of active webhooks for the user.
- **`DELETE /webhooks/{webhook_id}`**: Revokes a webhook.