# OpenMed API Endpoints: Complete REST API Reference for Medical NLP

> Explore the OpenMed API endpoints for medical NLP. This REST API reference details health checks, model management, text analysis, and PII extraction.

- Repository: [Maziyar Panahi/openmed](https://github.com/maziyarpanahi/openmed)
- Tags: api-reference
- Published: 2026-06-13

---

**OpenMed exposes six HTTP endpoints through a FastAPI application defined in [`openmed/service/app.py`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/service/app.py) with request validation handled by Pydantic schemas in [`openmed/service/schemas.py`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/service/schemas.py)) and is implemented at lines 216-226 in [`app.py`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/app.py).

## Usage Examples

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

Retrieve service health status:

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

```

List currently loaded models:

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

```

Unload a specific model:

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

```

Execute medical text analysis:

```bash
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:

```bash
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:

```bash
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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/service/schemas.py).
- **Runtime handling** occurs in [`openmed/service/runtime.py`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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.