# NOMAZRA API Endpoints — Documents & File Upload
Base URL: `https://nomazra.kelthos.com/api/nomazra/`

All endpoints require `Authorization: Bearer <access_token>`

---

## POST /upload/
Upload any file to R2 storage. Returns the file URL.

**Auth:** Bearer token  
**Content-Type:** multipart/form-data

**Request Fields:**
- `file` (required): The file to upload (max 50MB)
- `category` (optional): `"profile"`, `"documents"`, `"conversations"`, `"voice"`, `"temp"` (default: `"documents"`)

**Allowed file types:**
- PDF, DOC, DOCX, TXT, CSV
- JPEG, PNG, WEBP
- MP3, WAV, OGG, MP4 audio, WEBM audio

**Response 201:**
```json
{
  "key": "nomazra/user-uuid/documents/abc123_contract.pdf",
  "url": "https://54e0790c4fe8541ee53b29f8d0ba7ffd.r2.cloudflarestorage.com/kelthos-storage/nomazra/user-uuid/documents/abc123_contract.pdf",
  "content_type": "application/pdf",
  "size": 245678
}
```

**R2 folder structure:**
```
kelthos-storage/
  nomazra/
    {user_id}/
      profile/      ← avatar, profile pic
      documents/    ← uploaded legal docs
      conversations/ ← conversation attachments  
      voice/        ← voice recordings
      temp/         ← temporary files
```

**Errors:**
- 400: `{"error": "No file provided"}` / `{"error": "File too large (max 50MB)"}` / `{"error": "File type not allowed: ..."}`

---

## GET /documents/
List all user documents.

**Response 200:**
```json
[
  {
    "id": "uuid",
    "user": "user-uuid",
    "conversation": "conv-uuid or null",
    "file_url": "https://...",
    "file_type": "application/pdf",
    "original_name": "rental_contract.pdf",
    "extracted_text": "Full extracted text...",
    "analysis": {
      "summary": "AI-generated analysis...",
      "tokens_used": 823
    },
    "status": "completed",
    "created_at": "..."
  }
]
```

---

## POST /documents/
Upload and analyze a legal document. Supports direct file upload.

**Content-Type:** multipart/form-data

**Request Fields:**
- `file` (preferred): The document file
- OR: `file_url` + `original_name` + `file_type` (if already uploaded via /upload/)
- `conversation_id` (optional): Link document to a conversation

**What happens on upload:**
1. File uploaded to R2 under `nomazra/{user_id}/documents/`
2. Text extracted using file_converter:
   - PDF → pdfplumber (or OCR fallback for scanned PDFs)
   - DOCX → python-docx
   - Images → Tesseract OCR
   - Audio → Whisper API transcription
   - TXT/CSV → direct read
3. Extracted text sanitized (control chars removed, whitespace normalized)
4. GPT-4o-mini analyzes the document:
   - Document type and purpose
   - Key provisions/clauses
   - Notable legal implications
   - Potential issues or missing elements
5. Analysis saved to `document.analysis` JSON field
6. User stats updated (document count)

**Response 201:**
```json
{
  "id": "uuid",
  "file_url": "https://...",
  "file_type": "application/pdf",
  "original_name": "rental_contract.pdf",
  "extracted_text": "RENTAL AGREEMENT...",
  "analysis": {
    "summary": "This is a residential rental agreement...",
    "tokens_used": 823
  },
  "status": "completed",
  "created_at": "..."
}
```

**Errors:**
- 400: `{"error": "Provide a file upload or file_url + original_name"}` / `{"error": "File too large (max 50MB)"}` / `{"error": "File type not allowed"}`

---

## GET /documents/{id}/
Get a single document with analysis.

**Response 200:** Full document object.

---

## DELETE /documents/{id}/
Delete a document. Also deletes the file from R2 storage.

**Response 204:** No content.
