docs/API.md

SanjeevaniAI — REST API Reference (v1)

Base URL: http://localhost:8000/api/v1
Interactive OpenAPI UI: http://localhost:8000/docs
ReDoc UI: http://localhost:8000/redoc

All successful responses follow the standardized JSON envelope:

{
  "success": true,
  "data": { ... },
  "message": "Optional descriptive status",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "timestamp": "2026-08-18T21:00:00Z"
}

---

1. Authentication Endpoints (/auth)

POST /auth/register

Create a new patient, clinician, or administrator account.

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "full_name": "Dr. Sarah Jenkins",
  "role": "DOCTOR"
}

Response (200 OK):

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 7200,
    "user": {
      "id": "c1f725a2-9426-4d1e-84b2-f3e498c0b5f1",
      "email": "user@example.com",
      "full_name": "Dr. Sarah Jenkins",
      "role": "DOCTOR",
      "is_active": true
    }
  }
}

POST /auth/login

Authenticate user with email and password.

---

2. Biomedical NER Endpoints (/ner)

POST /ner/analyze

Extract biomedical entities from arbitrary clinical text using the local RoBERTa-large BC5CDR model.

Request Body:

{
  "text": "The patient was prescribed metformin 500mg and lisinopril 10mg for type 2 diabetes mellitus and hypertension."
}

Response (200 OK):

{
  "success": true,
  "data": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": {
      "name": "roberta-large-bc5cdr",
      "version": "1.0.0",
      "provider": "local_pytorch",
      "device": "cuda:0",
      "status": "ready"
    },
    "entities": [
      {
        "text": "metformin",
        "label": "CHEMICAL",
        "start": 27,
        "end": 36,
        "confidence": 0.9998,
        "model": "roberta-large-bc5cdr"
      },
      {
        "text": "lisinopril",
        "label": "CHEMICAL",
        "start": 47,
        "end": 57,
        "confidence": 0.9996,
        "model": "roberta-large-bc5cdr"
      },
      {
        "text": "type 2 diabetes mellitus",
        "label": "DISEASE",
        "start": 68,
        "end": 92,
        "confidence": 0.9985,
        "model": "roberta-large-bc5cdr"
      },
      {
        "text": "hypertension",
        "label": "DISEASE",
        "start": 97,
        "end": 109,
        "confidence": 0.9992,
        "model": "roberta-large-bc5cdr"
      }
    ],
    "entity_count": 4,
    "processing_time_ms": 14.8,
    "text_length": 110
  }
}

GET /ner/model-info

Retrieve local model health, hardware device allocation, and parameter footprint.

---

3. Medical Document Management (/documents)

POST /documents/upload

Upload a medical report (multipart/form-data: PDF, DOCX, TXT).
Automatically extracts text, computes SHA-256 integrity hash, runs local BC5CDR entity recognition, and generates a non-diagnostic summary.

GET /documents

List all uploaded reports for the authenticated user.

GET /documents/{document_id}

Retrieve full structured analysis, raw text, and identified entity spans for a specific document.

DELETE /documents/{document_id}

Permanently remove a document and its associated analysis.

---

4. AI Consultation Assistant (/chat)

POST /chat/message

Send a clinical query to the AI assistant with automatic patient profile injection and red-flag triage.

Request Body:

{
  "message": "What are typical lifestyle considerations for managing Type 2 Diabetes?",
  "conversation_id": null
}

Response (200 OK):

{
  "success": true,
  "data": {
    "conversation_id": "d3b07384-d113-4632-bc5d-8521c7d2427a",
    "message": {
      "id": "e4a18295-e224-4743-9d7e-9632d8e3538b",
      "role": "assistant",
      "content": "Type 2 Diabetes management involves glycemic control, balanced nutrition, and regular physical activity.",
      "structured_data": {
        "summary": "Educational guidance on Type 2 Diabetes management strategies.",
        "possible_considerations": [
          "Consistent carbohydrate counting and complex fiber intake improve postprandial glucose stability.",
          "Regular aerobic and resistance exercise enhances insulin sensitivity."
        ],
        "questions_for_doctor": [
          "What is my target HbA1c range given my current medication regimen?",
          "Should I consult a certified diabetes educator (CDCES)?"
        ],
        "safety_warning": "SanjeevaniAI provides decision-support information, not definitive diagnosis. Always consult your physician.",
        "is_emergency": false,
        "emergency_instructions": null
      },
      "model_provider": "Google Gemini / Local Clinical Engine"
    },
    "disclaimer": "SanjeevaniAI provides AI-assisted healthcare information and decision-support insights. It is not a substitute for professional medical diagnosis, treatment, or emergency care."
  }
}

---

5. Patient Profile (/profile)

GET /profile

Retrieve authenticated user's clinical profile.

PUT /profile

Update age, gender, blood group, height, weight, allergies, chronic conditions, and current medications.

---

6. History & Timeline (/history)

GET /history?limit=50

Retrieve chronological activity records with entity counts and timestamps.

---

7. Administrator Telemetry & Auditing (/admin)

GET /admin/stats (Admin Only)

Platform aggregates: total users, total documents, extracted entities count, and neural model device status.

GET /admin/audit-logs?limit=100 (Admin Only)

Security audit records covering logins, uploads, deletions, and administrative actions.