API Documentation

Complete reference for the Nuvii API endpoints and authentication. New to Nuvii? Get your free API key to get started.

Interactive API Testing

Try out the API endpoints interactively with our Swagger UI interface. Test requests, view responses, and explore all available endpoints.

Open Interactive Swagger UI

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

https://api.nuvii.ai

Endpoints

ICD-10 Diagnosis Codes

GET

Keyword Search

Search by code or description using exact keyword matching

GET /api/v1/icd10/search?query=diabetes&limit=10

GET

Semantic Search (AI-Powered)

Search using natural language - finds codes based on clinical meaning, not just keywords

GET /api/v1/icd10/semantic-search?query=patient%20with%20chest%20pain&min_similarity=0.7&year=2026

Parameters: query, code_system, version_year, limit, min_similarity

GET

Hybrid Search (Recommended)

Combines semantic AI and keyword matching - best of both worlds

GET /api/v1/icd10/hybrid-search?query=diabetes%20kidney%20complications&semantic_weight=0.7&year=2026

Parameters: query, code_system, version_year, semantic_weight (0-1), limit
Tip: semantic_weight=0.7 (default) balances AI understanding with keyword precision

GET

Faceted Search (Filter by Clinical Attributes)

Filter codes by body system, severity, chronicity, and other clinical facets

GET /api/v1/icd10/faceted-search?body_system=Cardiovascular&severity=Severe

Facets: body_system, concept_type, chronicity, severity, acuity, risk_flag

GET

Advanced Search (Re-ranking + Rules)

NEW

High-accuracy search with cross-encoder re-ranking and coding rules validation

GET /api/v1/icd10/advanced-search?query=hypertension&use_reranker=true&apply_rules=true&patient_age=65

Parameters: query, limit, use_reranker, apply_rules, patient_age, patient_gender
Returns: Score breakdown (vector, BM25, cross-encoder, rules), rule violations, explanations

GET

Multi-Query Search (Query Expansion)

NEW

Expands abbreviations and adds synonyms using LLM - “HTN” searches for hypertension, high blood pressure, etc.

GET /api/v1/icd10/multi-query-search?query=CHF&use_llm_expansion=true

Parameters: query, limit, use_llm_expansion, use_reranker, apply_rules
Supported abbreviations: HTN, CHF, COPD, DM, T2DM, CKD, CVA, GERD, MI, DVT, PE, and 40+ more

GET

Query Expansion Preview

NEW

Preview how a query will be expanded before searching

GET /api/v1/icd10/expand-query?query=HTN&use_llm=true

Returns: synonyms, abbreviation_expansions, clinical_terms, total_variants

Procedure Codes (CPT/HCPCS)

GET

Keyword Search

Search procedure codes by code or description

GET /api/v1/procedure/search?query=office%20visit&code_system=CPT&year=2025

Parameters: query, code_system (CPT/HCPCS), version_year, limit

GET

Semantic Search (AI-Powered)

Natural language search - “blood sugar test” finds glucose testing codes

GET /api/v1/procedure/semantic-search?query=knee%20surgery&min_similarity=0.6

GET

Hybrid Search (Recommended)

Combines AI and keyword matching for best results

GET /api/v1/procedure/hybrid-search?query=knee%20arthroscopy&semantic_weight=0.7

GET

Faceted Search

Filter by body region, complexity, service location, E/M level, imaging type, etc.

GET /api/v1/procedure/faceted-search?procedure_category=evaluation&em_level=level_3

Facets: body_region, body_system, procedure_category, complexity_level, service_location, em_level, imaging_modality

GET

Get Code Details

Get detailed information, facets, and mappings for a specific code

GET /api/v1/procedure/99213?code_system=CPT&version_year=2025

POST

Suggest Codes from Clinical Text

Analyze clinical documentation and suggest appropriate procedure codes

POST /api/v1/procedure/suggest?clinical_text=Patient%20for%20wellness%20exam&min_similarity=0.7

Use Case: Automated coding assistance, EHR integration, compliance checking

GET

Advanced Search (Re-ranking + CCI Rules)

NEW

High-accuracy search with cross-encoder re-ranking and CCI edit checking

GET /api/v1/procedure/advanced-search?query=arthroscopy&use_reranker=true&apply_rules=true&selected_codes=29881

Parameters: query, limit, use_reranker, apply_rules, selected_codes (for CCI bundling check)
Returns: Score breakdown, CCI violations, bundling warnings

GET

Multi-Query Search (Query Expansion)

NEW

Expands medical abbreviations - “EKG” finds electrocardiogram codes, “MRI” finds magnetic resonance imaging

GET /api/v1/procedure/multi-query-search?query=CT%20scan&use_llm_expansion=true

Parameters: query, limit, use_llm_expansion, use_reranker, apply_rules, selected_codes

Medicare Fee Schedule

Access CMS Medicare Physician Fee Schedule (MPFS) data with RVU-based pricing and geographic adjustments.

GET

Price Lookup

Get Medicare reimbursement price for a CPT/HCPCS code at a specific location

GET /api/v1/fee-schedule/price?code=99213&zip=10001&year=2025&setting=non_facility

Returns: Price, RVU breakdown (Work, PE, MP), GPCI values, national vs local pricing

GET

Code Search

Search fee schedule by code or description with RVU details

GET /api/v1/fee-schedule/search?query=office%20visit&year=2025&limit=20

Parameters: query, year, limit, offset

GET

Locality Lookup

Get CMS locality and GPCI values for a ZIP code

GET /api/v1/fee-schedule/locality?zip=90210&year=2025

Returns: Locality name, Work GPCI, PE GPCI, MP GPCI

GET

List Localities

List all CMS localities with GPCI values, optionally filter by state

GET /api/v1/fee-schedule/localities?year=2025&state=CA

GET

Conversion Factor

Get the Medicare conversion factor for a given year

GET /api/v1/fee-schedule/conversion-factor?year=2025

POST

Contract Analyzer

Analyze contracted rates against Medicare baseline to identify underpaid codes

POST /api/v1/fee-schedule/analyze

Body: { codes: [{code, rate, volume}], zip_code, year, setting }
Returns: Variance analysis, red flags (codes >10% below Medicare), revenue impact

POST

Contract Analyzer (CSV Upload)

Upload a CSV file for bulk contract analysis

POST /api/v1/fee-schedule/analyze/upload?zip_code=10001&year=2025

CSV Columns: code, rate, volume (optional), description (optional)

GET

Available Years

Get list of years with available fee schedule data

GET /api/v1/fee-schedule/years

Rate Limits

Per Minute: 60 requests (Free), 300 requests (Developer), 1000 requests (Growth)

Per Day: 10,000 requests (adjusts based on your plan)

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Need higher limits? View our pricing plans or contact us for custom enterprise solutions.

Error Codes

400Bad Request - Invalid parameters

401Unauthorized - Invalid or missing API key

429Too Many Requests - Rate limit exceeded

500Internal Server Error - Something went wrong

Need help troubleshooting? Contact our support team for assistance.