OpenMed API Endpoints: Complete REST API Reference for Medical NLP

OpenMed exposes six HTTP endpoints through a FastAPI application defined in openmed/service/app.py, covering health checks, model management, text analysis, and PII extraction/de-identification.

The OpenMed API provides a minimal yet powerful REST interface for medical NLP tasks. According to the maziyarpanahi/openmed source code, the service routes are implemented in openmed/service/app.py with request validation handled by Pydantic schemas in openmed/service/schemas.py. Understanding these OpenMed API endpoints enables seamless integration of clinical entity recognition and patient data de-identification into healthcare applications.

Available OpenMed API Endpoints

The FastAPI application defines six distinct routes organized by functionality. Each endpoint uses standard HTTP methods and accepts JSON payloads validated against strict Pydantic models.

Health and Monitoring Endpoints

GET /health

The health check endpoint returns the service name, version, runtime profile, and operational status. As implemented in openmed/service/app.py (lines 202-209), this endpoint provides essential uptime monitoring for containerized deployments.

GET /models/loaded

This endpoint lists all currently loaded models along with their cache states and keep-alive timer configurations. Located at lines 211-215 in app.py, it enables runtime introspection of model availability before submitting analysis requests.

Model Management Endpoints

POST /models/unload

Use this endpoint to unload specific models from memory or clear all cached models simultaneously. The endpoint accepts a ModelUnloadRequest payload (defined in openmed/service/schemas.py) and is implemented at lines 216-226 in app.py. This is critical for managing GPU memory in production environments.

Text Analysis and PII Endpoints

POST /analyze

The primary analysis endpoint executes named entity recognition, classification, and other medical NLP tasks. It accepts an AnalyzeRequest payload containing the input text, target model name, confidence threshold, and keep-alive duration. The implementation resides at lines 227-238 in openmed/service/app.py.

POST /pii/extract

This endpoint detects personally identifiable information (PII) in clinical text using specialized models. Validated by the PIIExtractRequest schema, the handler at lines 240-250 in app.py supports entity extraction for patient names, dates, addresses, and medical record numbers.

POST /pii/deidentify

The de-identification endpoint masks, removes, replaces, hashes, or date-shifts detected PII according to the specified method. Using the PIIDeidentifyRequest schema (lines 252-267 in app.py), this endpoint supports HIPAA-compliant text sanitization with optional mapping preservation.

Request Schemas and Validation

All POST endpoints enforce strict input validation through Pydantic models defined in openmed/service/schemas.py. The four primary schemas include:

• AnalyzeRequest: Validates analysis text, model selection, confidence thresholds, and keep-alive settings
• PIIExtractRequest: Validates text input, language codes, and PII model specifications
• PIIDeidentifyRequest: Validates de-identification methods (mask, remove, replace, hash, shift_dates) and mapping retention flags
• ModelUnloadRequest: Validates target model names or global unload operations

These schemas ensure type safety and prevent invalid model configurations before reaching the runtime layer.

Runtime Architecture

The backend processing relies on openmed/service/runtime.py, which handles model loading, keep-alive timer management, and request bookkeeping. When you call the OpenMed API endpoints, the runtime layer manages GPU memory allocation and model caching strategies independently of the HTTP interface defined in app.py.

Usage Examples

The following examples demonstrate interaction with each OpenMed API endpoint using standard HTTP clients.

Retrieve service health status:

curl -s http://localhost:8000/health | jq

List currently loaded models:

curl -s http://localhost:8000/models/loaded | jq

Unload a specific model:

curl -X POST -H "Content-Type: application/json" \
     -d '{"model_name":"disease_detection_superclinical"}' \
     http://localhost:8000/models/unload | jq

Execute medical text analysis:

curl -X POST -H "Content-Type: application/json" \
     -d '{
           "text":"Patient shows signs of pneumonia.",
           "model_name":"disease_detection_superclinical",
           "confidence_threshold":0.6,
           "keep_alive":300
         }' \
     http://localhost:8000/analyze | jq

Extract PII from clinical notes:

curl -X POST -H "Content-Type: application/json" \
     -d '{
           "text":"John Doe, born 1990-01-01, lives at 123 Main St.",
           "model_name":"OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1",
           "lang":"en"
         }' \
     http://localhost:8000/pii/extract | jq

De-identify text with masking:

curl -X POST -H "Content-Type: application/json" \
     -d '{
           "text":"John Doe, born 1990-01-01, lives at 123 Main St.",
           "method":"mask",
           "model_name":"OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1",
           "keep_mapping":true
         }' \
     http://localhost:8000/pii/deidentify | jq

Summary

• OpenMed API endpoints are defined in openmed/service/app.py using FastAPI, providing six routes for health monitoring, model management, and medical NLP tasks.
• GET endpoints (/health, /models/loaded) support service monitoring and cache introspection without request bodies.
• POST endpoints (/models/unload, /analyze, /pii/extract, /pii/deidentify) accept JSON payloads validated by Pydantic schemas in openmed/service/schemas.py.
• Runtime handling occurs in openmed/service/runtime.py, managing model lifecycles and GPU memory independently of the HTTP layer.
• All endpoints follow REST conventions with standard HTTP status codes and JSON responses.

Frequently Asked Questions

What base URL does the OpenMed API use?

The OpenMed API endpoints run on the host and port configured when starting the FastAPI application. By default, the service listens on http://localhost:8000 unless overridden by environment variables or deployment configuration. The base path for all endpoints is the root /, making the full health check URL http://localhost:8000/health.

How does OpenMed validate API requests?

OpenMed validates all POST requests using Pydantic models defined in openmed/service/schemas.py. Each endpoint has a specific schema—AnalyzeRequest, PIIExtractRequest, PIIDeidentifyRequest, or ModelUnloadRequest—that enforces type constraints, required fields, and value ranges before processing. Invalid requests return HTTP 422 errors with detailed validation messages.

Can I unload multiple models at once using the OpenMed API?

Yes, the /models/unload endpoint supports unloading all cached models simultaneously. According to the ModelUnloadRequest schema implementation, sending a specific model name targets that model for removal, while omitting the model name or using a wildcard triggers a complete cache flush. This functionality is handled at lines 216-226 in openmed/service/app.py.

What is the difference between PII extraction and de-identification in OpenMed?

PII extraction (/pii/extract) identifies and returns detected entities such as patient names, dates, and addresses without modifying the original text. PII de-identification (/pii/deidentify) transforms the input text using methods like masking, hashing, or date shifting to create HIPAA-compliant outputs. Both endpoints use the openmed/service/runtime.py layer for model inference but apply different post-processing logic as defined in their respective handlers at lines 240-250 and 252-267.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}