Hospital API Documentation

Base URL:https://api.docdroid.ai/api/v1/hospital

Authentication

All API requests must include a Bearer token in the Authorization header. API keys are provisioned through the hospital admin dashboard.

Authorization: Bearer your_api_key_here

Rate limit: 60 requests per minute per API key.

Patient Access

GET/patients

List all patients who have granted consent to your hospital. Returns paginated results.

Parameters

pageintegerPage number (default: 1)

limitintegerResults per page (default: 20, max: 100)

searchstringSearch by patient name or ID

Response Example

{
  "data": [
    {
      "id": "pat_8f3a2b1c",
      "name": "Ahmed Al-Mansoori",
      "date_of_birth": "1985-03-12",
      "consent_status": "active",
      "consent_granted_at": "2026-03-15T10:30:00Z",
      "last_report_date": "2026-03-28T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142
  }
}

GET/patients/:patient_id

Retrieve detailed profile and consent information for a specific patient.

Parameters

patient_idstringThe unique patient identifier

Response Example

{
  "id": "pat_8f3a2b1c",
  "name": "Ahmed Al-Mansoori",
  "date_of_birth": "1985-03-12",
  "gender": "male",
  "blood_type": "O+",
  "consent": {
    "status": "active",
    "granted_at": "2026-03-15T10:30:00Z",
    "expires_at": "2027-03-15T10:30:00Z",
    "scopes": ["records.read", "briefs.create", "analysis.request"]
  },
  "reports_count": 24,
  "last_report_date": "2026-03-28T14:00:00Z"
}

GET/patients/:patient_id/records

Retrieve health records for a consented patient. Includes lab reports, extracted biomarkers, and AI interpretations.

Parameters

patient_idstringThe unique patient identifier

fromstringStart date filter (ISO 8601)

tostringEnd date filter (ISO 8601)

categorystringFilter by report category (e.g. blood, urine, imaging)

Response Example

{
  "data": [
    {
      "id": "rec_4d7e1a9f",
      "report_date": "2026-03-28T14:00:00Z",
      "category": "blood",
      "lab_name": "Al Borg Diagnostics",
      "biomarkers": [
        {
          "name": "Hemoglobin",
          "value": 13.8,
          "unit": "g/dL",
          "reference_range": "13.0-17.0",
          "status": "normal"
        },
        {
          "name": "Fasting Glucose",
          "value": 118,
          "unit": "mg/dL",
          "reference_range": "70-100",
          "status": "high"
        }
      ],
      "ai_interpretation": "Hemoglobin levels are within normal range. Fasting glucose is elevated, suggesting pre-diabetic levels. Recommend follow-up HbA1c test."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 24
  }
}

AI Briefs

POST/patients/:patient_id/briefs

Request an AI-generated doctor brief summarizing the patient's health history, trends, and key findings.

Parameters

patient_idstringThe unique patient identifier

Request Body

{
  "focus_areas": ["cardiovascular", "metabolic"],
  "date_range": {
    "from": "2025-01-01",
    "to": "2026-03-28"
  },
  "include_trends": true,
  "language": "en"
}

Response Example

{
  "id": "brief_2c8f4e1a",
  "status": "completed",
  "created_at": "2026-03-29T09:15:00Z",
  "patient_id": "pat_8f3a2b1c",
  "summary": "Patient is a 41-year-old male with trending elevated fasting glucose over the past 6 months (102 -> 118 mg/dL). LDL cholesterol has improved from 155 to 128 mg/dL following statin therapy. Blood pressure readings remain within normal limits. HbA1c of 6.1% from January 2026 confirms pre-diabetic status.",
  "key_findings": [
    {
      "category": "metabolic",
      "finding": "Progressive glucose elevation suggesting pre-diabetes",
      "severity": "moderate",
      "trend": "worsening"
    },
    {
      "category": "cardiovascular",
      "finding": "LDL cholesterol improving with current treatment",
      "severity": "low",
      "trend": "improving"
    }
  ],
  "recommendations": [
    "Consider HbA1c retest in 3 months",
    "Continue current statin therapy",
    "Recommend dietary consultation for glucose management"
  ]
}

GET/patients/:patient_id/briefs/:brief_id

Retrieve a previously generated doctor brief by its ID.

Parameters

patient_idstringThe unique patient identifier

brief_idstringThe brief identifier

Response Example

{
  "id": "brief_2c8f4e1a",
  "status": "completed",
  "created_at": "2026-03-29T09:15:00Z",
  "patient_id": "pat_8f3a2b1c",
  "summary": "Patient is a 41-year-old male with trending elevated fasting glucose...",
  "key_findings": [...],
  "recommendations": [...]
}

Analysis Requests

POST/patients/:patient_id/analysis

Submit a targeted analysis request for specific biomarkers, conditions, or health trends.

Parameters

patient_idstringThe unique patient identifier

Request Body

{
  "type": "trend_analysis",
  "biomarkers": ["fasting_glucose", "hba1c", "insulin"],
  "date_range": {
    "from": "2025-06-01",
    "to": "2026-03-28"
  },
  "notes": "Evaluate diabetes risk progression"
}

Response Example

{
  "id": "analysis_7b3d9e2f",
  "status": "processing",
  "created_at": "2026-03-29T10:00:00Z",
  "patient_id": "pat_8f3a2b1c",
  "estimated_completion": "2026-03-29T10:02:00Z"
}

GET/patients/:patient_id/analysis/:analysis_id

Retrieve the results of a previously submitted analysis request.

Parameters

patient_idstringThe unique patient identifier

analysis_idstringThe analysis request identifier

Response Example

{
  "id": "analysis_7b3d9e2f",
  "status": "completed",
  "created_at": "2026-03-29T10:00:00Z",
  "completed_at": "2026-03-29T10:01:45Z",
  "patient_id": "pat_8f3a2b1c",
  "type": "trend_analysis",
  "results": {
    "trend_summary": "Fasting glucose shows a steady upward trend over 10 months, increasing from 98 to 118 mg/dL. HbA1c rose from 5.7% to 6.1%. Insulin levels remain within normal range at 12.4 uIU/mL.",
    "risk_assessment": "moderate",
    "data_points": [
      { "date": "2025-06-15", "biomarker": "fasting_glucose", "value": 98, "unit": "mg/dL" },
      { "date": "2025-09-20", "biomarker": "fasting_glucose", "value": 105, "unit": "mg/dL" },
      { "date": "2025-12-10", "biomarker": "fasting_glucose", "value": 112, "unit": "mg/dL" },
      { "date": "2026-03-28", "biomarker": "fasting_glucose", "value": 118, "unit": "mg/dL" }
    ]
  }
}

GET/analysis

List all analysis requests made by your hospital across all patients.

Parameters

statusstringFilter by status: processing, completed, failed

pageintegerPage number (default: 1)

limitintegerResults per page (default: 20)

Response Example

{
  "data": [
    {
      "id": "analysis_7b3d9e2f",
      "patient_id": "pat_8f3a2b1c",
      "type": "trend_analysis",
      "status": "completed",
      "created_at": "2026-03-29T10:00:00Z"
    },
    {
      "id": "analysis_1a5c8d4b",
      "patient_id": "pat_6e2f9c3d",
      "type": "condition_screening",
      "status": "processing",
      "created_at": "2026-03-29T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 87
  }
}