Documentation

API Reference

Complete reference for the arxio Clinical Decision Support API. All endpoints require authentication and return JSON responses.

Quickstart

Get your first clinical review in under 60 seconds.

Get your API key

Make your first call

Send a POST to /v1/clinical-review with a drug, patient, and active medications.

Get safety flags in <200ms

The response includes 6 DUR categories, each with status (clear or flagged), findings, and an overall risk level.

Authentication

All API requests (except /v1/health) must include your API key in the X-API-Key header.

Header

X-API-Key: arx_sk_your_api_key_here

Security: Never expose your API key in client-side code. Always make API calls from your backend server.

Base URL

https://api.arxio.health

Rate Limiting

Rate limits are applied per API key on a daily basis. Limits reset at midnight UTC.

Plan	Daily Limit	Burst Rate
Free	100 requests/day	10 requests/minute
Pro	10,000 requests/day	100 requests/minute
Enterprise	Unlimited	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1710374400

Errors

The API uses standard HTTP status codes. All errors return a JSON body with a detail field.

Status	Meaning	Common Cause
400	Bad Request	Invalid request body or missing required fields
401	Unauthorized	Missing or invalid API key
404	Not Found	Drug NDC or resource not found
422	Validation Error	Request body failed schema validation
429	Rate Limited	Daily request limit exceeded
503	Service Unavailable	LLM engine temporarily unavailable

Error response

{
  "detail": "Daily rate limit exceeded. Resets at midnight UTC."
}

Endpoints

POST/v1/clinical-review

Clinical Review

Run a comprehensive 6-category Drug Utilization Review on a prescription. Returns safety flags for drug interactions, allergy screening, dose range validation, patient profile analysis, duplicate therapy detection, and prescriber credential verification.

Request Body

application/json

{
  "drug": {
    "drug_name": "metronidazole",
    "generic_name": "metronidazole",
    "ndc": "00093-0812-01",
    "dosage_form": "tablet",
    "strength": "500mg",
    "route": "oral"
  },
  "patient": {
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1954-06-15",
    "gender": "M",
    "allergies": [
      { "substance": "sulfa", "reaction": "rash", "severity": "moderate" },
      { "substance": "penicillin", "reaction": "anaphylaxis", "severity": "severe" }
    ],
    "conditions": ["atrial_fibrillation", "hypertension"]
  },
  "prescriber": {
    "name": "Dr. Jane Smith",
    "npi": "1234567893",
    "dea": "AS1234563"
  },
  "active_medications": [
    {
      "drug_name": "warfarin",
      "ndc": "00056-0170-70",
      "quantity": 30,
      "days_supply": 30,
      "refills": 3,
      "sig": "Take 5mg PO daily"
    },
    {
      "drug_name": "lisinopril",
      "sig": "Take 10mg PO daily"
    }
  ],
  "quantity": 30,
  "days_supply": 10,
  "refills": 0,
  "sig": "Take 500mg PO TID with food"
}

Response

200 OK

{
  "dur_review": {
    "status": "flagged",
    "findings": [
      {
        "type": "overall_risk",
        "severity": "high",
        "description": "High-risk prescription due to warfarin-metronidazole interaction",
        "recommendation": "Requires pharmacist intervention before dispensing"
      }
    ]
  },
  "drug_interactions": {
    "status": "flagged",
    "findings": [
      {
        "type": "drug_interaction",
        "severity": "high",
        "description": "Warfarin + Metronidazole: significantly increased bleeding risk via CYP2C9 inhibition. Expected INR elevation of 30-50%.",
        "recommendation": "Monitor INR closely. Consider warfarin dose reduction by 25-50% during metronidazole course."
      }
    ]
  },
  "allergy_screening": {
    "status": "clear",
    "findings": []
  },
  "dose_range": {
    "status": "clear",
    "findings": [
      {
        "type": "dose_info",
        "severity": "info",
        "description": "500mg TID is within standard adult dosing range for metronidazole.",
        "recommendation": "No adjustment needed."
      }
    ]
  },
  "patient_profile": {
    "status": "flagged",
    "findings": [
      {
        "type": "age_consideration",
        "severity": "moderate",
        "description": "Patient age 71: consider renal function (CrCl) for dose adjustment.",
        "recommendation": "Verify eGFR before dispensing. Reduce dose if CrCl < 30 mL/min."
      }
    ]
  },
  "prescriber_credentials": {
    "status": "clear",
    "findings": []
  },
  "overall_risk": "high",
  "reasoning": "High-severity drug interaction between warfarin and metronidazole requires pharmacist review. All other categories clear.",
  "model": "qwen3:8b-optimized",
  "generated_at": "2026-03-15T14:30:00Z",
  "eval_duration_ms": 142
}

Code Examples

curl -X POST https://api.arxio.health/v1/clinical-review \
  -H "X-API-Key: arx_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "drug": {
      "drug_name": "metronidazole",
      "strength": "500mg",
      "route": "oral"
    },
    "patient": {
      "date_of_birth": "1954-06-15",
      "gender": "M",
      "allergies": [
        { "substance": "sulfa", "severity": "moderate" }
      ],
      "conditions": ["atrial_fibrillation"]
    },
    "active_medications": [
      { "drug_name": "warfarin", "sig": "5mg PO daily" }
    ],
    "quantity": 30,
    "days_supply": 10,
    "sig": "500mg PO TID with food"
  }'

POST/v1/prescribe-assist

Prescribe-Assist

AI-powered prescription generation. Provide a drug and patient context to receive a complete Rx recommendation with classification, dosing, sig, substitution allowance, and clinical reasoning.

Request Body

application/json

{
  "drug": {
    "drug_name": "amoxicillin",
    "generic_name": "amoxicillin",
    "dosage_form": "capsule",
    "strength": "500mg",
    "route": "oral"
  },
  "patient": {
    "first_name": "Sarah",
    "last_name": "Johnson",
    "date_of_birth": "1992-03-22",
    "gender": "F",
    "allergies": [],
    "conditions": []
  },
  "prescriber_npi": "1234567893",
  "active_medications": [
    {
      "drug_name": "oral contraceptive",
      "sig": "Take 1 tablet PO daily"
    }
  ]
}

Response

200 OK

{
  "rx_classification": "Rx",
  "classification_reasoning": "Amoxicillin is a prescription-only antibiotic requiring a valid prescription.",
  "quantity": 21,
  "days_supply": 7,
  "refills": 0,
  "sig_text": "Take 500mg (1 capsule) by mouth three times daily for 7 days",
  "substitutions": 1,
  "reasoning": "Standard adult dose for mild-moderate infection. 7-day course appropriate. Generic substitution permitted. Note: may reduce efficacy of oral contraceptives — advise backup contraception.",
  "drug_name": "amoxicillin",
  "ndc": "00093-3109-01",
  "model": "qwen3:8b-optimized",
  "generated_at": "2026-03-15T14:31:00Z",
  "eval_duration_ms": 118
}

Code Examples

curl -X POST https://api.arxio.health/v1/prescribe-assist \
  -H "X-API-Key: arx_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "drug": {
      "drug_name": "amoxicillin",
      "strength": "500mg",
      "route": "oral"
    },
    "patient": {
      "gender": "F",
      "date_of_birth": "1992-03-22",
      "allergies": [],
      "conditions": []
    },
    "prescriber_npi": "1234567893",
    "active_medications": [
      { "drug_name": "oral contraceptive" }
    ]
  }'

GET/v1/drugs/search?q={query}&limit={limit}

Drug Search

Search the drug database by name or NDC prefix. Returns matching medications with dosage forms, strengths, routes, and NDC codes. Minimum 2-character query, max 50 results.

Response

200 OK

{
  "drugs": [
    {
      "id": "d1a2b3c4-5678-9012-abcd-ef0123456789",
      "ndc": "00087-6060-05",
      "drug_name": "METFORMIN HYDROCHLORIDE",
      "generic_name": "metformin",
      "dosage_form": "TABLET",
      "strength": "500mg",
      "route": "ORAL",
      "manufacturer": "Bristol-Myers Squibb",
      "dea_schedule": "",
      "package_description": "500 TABLET in 1 BOTTLE"
    },
    {
      "id": "e2b3c4d5-6789-0123-bcde-f01234567890",
      "ndc": "00087-6070-05",
      "drug_name": "METFORMIN HYDROCHLORIDE",
      "generic_name": "metformin",
      "dosage_form": "TABLET",
      "strength": "850mg",
      "route": "ORAL",
      "manufacturer": "Bristol-Myers Squibb",
      "dea_schedule": "",
      "package_description": "500 TABLET in 1 BOTTLE"
    }
  ],
  "total": 2
}

Code Examples

curl "https://api.arxio.health/v1/drugs/search?q=metformin&limit=5" \
  -H "X-API-Key: arx_sk_abc123"

GET/v1/drugs/{ndc}

Drug Lookup by NDC

Retrieve detailed drug information by National Drug Code. Returns the full drug record including dosage form, strength, route, manufacturer, DEA schedule, and package description.

Response

200 OK

{
  "id": "d1a2b3c4-5678-9012-abcd-ef0123456789",
  "ndc": "00087-6060-05",
  "drug_name": "METFORMIN HYDROCHLORIDE",
  "generic_name": "metformin",
  "dosage_form": "TABLET",
  "strength": "500mg",
  "route": "ORAL",
  "manufacturer": "Bristol-Myers Squibb",
  "dea_schedule": "",
  "package_description": "500 TABLET in 1 BOTTLE"
}

Code Examples

curl "https://api.arxio.health/v1/drugs/00087-6060-05" \
  -H "X-API-Key: arx_sk_abc123"

GET/v1/npi/validate/{npi}

NPI Validation

Validate a National Provider Identifier using Luhn-10 checksum verification and live NPPES Registry lookup. Returns provider details including name, credential, specialty, and practice location.

Response

200 OK

{
  "valid": true,
  "message": "Valid NPI — JANE SMITH",
  "npi": "1234567893",
  "found": true,
  "name": "JANE SMITH",
  "credential": "MD",
  "gender": "F",
  "enumeration_type": "individual",
  "specialty": "Internal Medicine",
  "address_city": "SAN FRANCISCO",
  "address_state": "CA",
  "status": "active"
}

Code Examples

curl "https://api.arxio.health/v1/npi/validate/1234567893" \
  -H "X-API-Key: arx_sk_abc123"

GET/v1/health

Health Check

Public endpoint (no authentication required). Returns service status, name, and version. Use for uptime monitoring and connectivity checks.

Response

200 OK

{
  "status": "healthy",
  "service": "arxio-cds",
  "version": "0.1.0"
}

Code Examples

curl "https://api.arxio.health/v1/health"

API Reference

On This Page

Quickstart

Authentication

Base URL

Rate Limiting

Errors

Endpoints

Clinical Review

Request Body

Response

Code Examples

Prescribe-Assist

Request Body

Response

Code Examples

Drug Search

Response

Code Examples

Drug Lookup by NDC

Response

Code Examples

NPI Validation

Response

Code Examples

Health Check

Response

Code Examples