BACKEND_API.md

Backend API Contract — Frontend Reference

Base URL: http://localhost:8000

Authentication

All endpoints except /auth/* and /health//ready require:

Authorization: Bearer <access_token>

Auth Endpoints

Method	Path	Request	Response
POST	/auth/register	{ email, password, first_name?, last_name? }	UserResponse
POST	/auth/login	{ email, password }	{ access_token, user_id, roles }
POST	/auth/logout	—	204
GET	/auth/token/refresh	—	{ access_token }
POST	/auth/mfa/setup	—	{ secret, uri, qr_code_url }
POST	/auth/mfa/verify	{ code }	UserResponse
GET	/auth/oauth/config	—	{ github_client_id }
POST	/auth/oauth/github	{ code }	LoginResponse

Documents

Upload — POST /documents

Content-Type: multipart/form-data
Body: files[] = (binary PDF files)

Returns { uploaded_documents: [{ upload_id, document_id, filename, status }] }

Documents process asynchronously. Poll GET /uploads/{upload_id} for status.

List Documents — GET /documents

Response: [
  {
    id: string,
    filename: string,
    status: "processing" | "ready" | "failed",
    has_pii: bool,
    cloudinary_url: string | null,   // PDF viewing URL
    uploaded_by: string,
    created_at: string | null
  }
]

Get Document — GET /documents/{doc_id}

Returns single DocumentResponse (same shape as list item).

Delete Document — DELETE /documents/{doc_id}

204 No Content.

Backfill Cloudinary — POST /documents/backfill

Re-uploads old docs to Cloudinary. Returns { backfilled: number, total: number }.

Upload Status — GET /uploads/{upload_id}

{
  id, filename, stage, progress, error?, document_id?, user_id, created_at?, updated_at?
}

Stages: uploading → extracting → chunking → embedding → indexing → completed

Query

Non-streaming — POST /query

{
  "question": "what is attention?",
  "document_ids": ["uuid1", "uuid2"],   // optional, null = all docs
  "mode": "white_box",                   // "white_box" | "black_box"
  "max_citations": 20,                   // optional, 1-100
  "conversation_history": [              // optional, last 6 turns max
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ]
}

Response:

{
  "answer": "The Transformer uses multi-head attention... [1][2]",
  "citations": [
    {
      "quote": "excerpt from the document",
      "source": "attention_paper.pdf",       // filename
      "location": "page 3 / chunk 5",
      "page": 3,
      "document_id": "uuid"
    }
  ],
  "reasoning_path": ["Retrieved 6 citations across 2 hop(s)", "VERIFIED"],
  "tokens_used": 450,
  "cost_usd": 0.0009,
  "query_id": "hex",
  "verification": "VERIFIED"               // white_box only, null for black_box
}

Streaming — POST /query/stream

Same request body. Server-Sent Events (SSE):

data: {"type": "citations", "citations": [...], "query_id": "...", "reasoning_path": [...]}
data: {"type": "token", "content": "The"}
data: {"type": "token", "content": " Transformer"}
data: {"type": "token", "content": " uses..."}
data: {"type": "verification", "content": "VERIFIED"}       // white_box only
data: {"type": "gap_analysis", "content": "missing X"}       // white_box only, one per gap
data: {"type": "done", "tokens_used": 450, "cost_usd": 0.0009, "mode": "white_box", "query_id": "..."}
data: [DONE]

Citation click: Use citation.document_id → fetch GET /documents/{document_id} → read cloudinary_url → open in PDF viewer at that URL.

Analyze

POST /analyze

{
  "question": "Compare their methodologies",    // optional
  "document_ids": ["uuid1", "uuid2"],           // optional, null = error
  "max_citations": 20
}

Response:

{
  "summary": "Both papers use Transformer-based architectures...",
  "key_findings": ["Finding 1", "Finding 2", "..."],
  "methodology": "Description of methods...",
  "research_gaps": ["Gap 1", "Gap 2"],
  "contradictions": ["Contradiction 1"],
  "open_questions": ["Question 1"],
  "limitations": "Only 3 documents analyzed",
  "confidence": "high",
  "citations": [/* same Citation shape as query */],
  "documents_analyzed": ["doc-uuid-1", "doc-uuid-2"],
  "cross_document_comparison": {
    "common_themes": ["both use attention"],
    "differences": ["doc1 uses BERT, doc2 uses GPT"],
    "complementary_insights": ["doc1's findings on X support doc2's Y"]
  },                                      // null when single doc
  "per_document_summary": {
    "paper1.pdf": "Introduces Transformer...",
    "paper2.pdf": "Applies BERT to..."
  }                                       // null when single doc
}

PDF Viewer Flow

1. Query returns citations with document_id
2. Frontend user clicks citation [N]
3. Frontend calls GET /documents/{document_id} → gets cloudinary_url
4. Opens Cloudinary URL in PDF viewer (iframe or new tab)

Cloudinary URL format: https://res.cloudinary.com/da1nocxo0/image/upload/v.../{user_id}/{doc_id}.pdf

The cloudinary_url is always set for new uploads. For old docs, run POST /documents/backfill once.

Sessions (Chat History)

Method	Path	Notes
GET	/sessions	List all sessions
POST	/sessions	Create new session
GET	/sessions/{sid}	Session with messages
PUT	/sessions/{sid}	Update title
DELETE	/sessions/{sid}	Delete session
GET	/sessions/{sid}/messages	List messages
POST	/sessions/{sid}/messages	Add message
POST	/sessions/{sid}/feedback	Thumbs up/down

Query Modes

White Box (default)

• Temperature: default (some variation)
• Max tokens: 3048
• Streams: verification + gap_analysis events
• Multi-hop retrieval (up to 3 rounds)
• Reasoning path included
• Structured answer with sections

Black Box

• Temperature: 0 (deterministic)
• Max tokens: default (2048)
• No verification, no gap analysis, no reasoning
• Single-pass retrieval only
• Minimal answer — just the cited response, no commentary

Greeting Detection

All three endpoints (/query, /query/stream, /analyze) detect greetings and return a friendly message without calling the LLM or searching documents:

"Hi there! What would you like to know about your documents?"   // /query, /query/stream
"Hi there! Please select documents to analyze, or ask me a question about your documents."  // /analyze

Common Error Codes

Code	Meaning
401	Missing/invalid token
400	Guardrails blocked the query
413	File too large (max 50MB)
502	LLM provider unreachable
429	Rate limited (20/min for query, 10/min for analyze)