# Responses

Medical Device processing is synchronous — the extracted data is returned directly in the API response body. No callback configuration is required.

## Upload response (HTTP 201)

The top-level response wraps all file results in an `extractions` array, one entry per uploaded file.

```json
{
  "success": true,
  "data": {
    "type": "medical",
    "status": "extracted",
    "extractions": [
      {
        "fileName": "device-reading.png",
        "result": {
          "status": "extracted",
          "data": { ... },
          "message": "Medical data extracted successfully from PNG file"
        }
      }
    ],
    "filesCount": 1,
    "message": "1 medical file(s) processed successfully"
  }
}
```

### Upload response field reference

| Field | Type | Description |
|  --- | --- | --- |
| `success` | boolean | `true` when the request was processed (even if individual extractions failed) |
| `data.type` | string | Always `"medical"` |
| `data.status` | string | Always `"extracted"` on a completed request |
| `data.extractions` | array | One entry per uploaded file |
| `data.extractions[].fileName` | string | Original filename of the uploaded file |
| `data.extractions[].result` | object | Extraction result for this file — see single-device or multi-device format below |
| `data.filesCount` | integer | Number of files processed |
| `data.message` | string | Human-readable summary |


## Single-device extraction

When only one device is detected in the image, the result contains top-level device fields.

```json
{
  "status": "extracted",
  "data": {
    "success": true,
    "deviceType": "pulse-oximeter",
    "data": {
      "SpO2": "98%",
      "pulseRate": "87 BPM"
    },
    "confidence": 0.85,
    "timestamp": "2026-04-09T03:50:13.655Z",
    "processingTime": "1570ms"
  },
  "message": "Medical data extracted successfully from PNG file"
}
```

### Single-device result field reference

| Field | Type | Description |
|  --- | --- | --- |
| `data.success` | boolean | Whether extraction succeeded |
| `data.deviceType` | string | Detected device type (see supported devices below) |
| `data.data` | object | Extracted readings — keys vary by device type |
| `data.confidence` | number | AI confidence score (0.0–1.0) |
| `data.timestamp` | string | ISO 8601 timestamp of when processing occurred |
| `data.processingTime` | string | Processing duration, e.g. `"1570ms"` |


## Multi-device extraction

When the system detects more than one device in the image (or when multiple readings are found), the result contains an `items` array. The top-level `deviceType`, `data`, and `confidence` fields are omitted.

```json
{
  "status": "extracted",
  "data": {
    "success": true,
    "count": 2,
    "items": [
      {
        "index": 0,
        "deviceType": "blood-pressure-monitor",
        "data": {
          "systolic": "120 mmHg",
          "diastolic": "80 mmHg",
          "pulseRate": "72 BPM"
        },
        "confidence": 0.91,
        "verificationStatus": "verified"
      },
      {
        "index": 1,
        "deviceType": "pulse-oximeter",
        "data": {
          "SpO2": "97%",
          "pulseRate": "72 BPM"
        },
        "confidence": 0.88,
        "verificationStatus": "verified"
      }
    ],
    "timestamp": "2026-04-09T03:50:13.655Z",
    "processingTime": "2340ms"
  },
  "message": "Medical data extracted successfully from PNG file"
}
```

### Multi-device result field reference

| Field | Type | Description |
|  --- | --- | --- |
| `data.success` | boolean | Whether extraction succeeded |
| `data.count` | integer | Number of devices detected |
| `data.items` | array | One entry per detected device |
| `data.items[].index` | integer | Zero-based position in the detection order |
| `data.items[].deviceType` | string | Detected device type |
| `data.items[].data` | object | Extracted readings for this device |
| `data.items[].confidence` | number | Per-device confidence score (0.0–1.0) |
| `data.items[].verificationStatus` | string | Verification state, e.g. `"verified"` |
| `data.timestamp` | string | ISO 8601 timestamp of processing |
| `data.processingTime` | string | Processing duration, e.g. `"2340ms"` |


## Supported device types

| `deviceType` | Example extracted fields |
|  --- | --- |
| `pulse-oximeter` | `SpO2`, `pulseRate` |
| `blood-pressure-monitor` | `systolic`, `diastolic`, `pulseRate` |
| `glucometer` | `bloodGlucose`, `unit` |
| `thermometer` | `temperature`, `unit` |
| `weight-scale` | `weight`, `unit` |
| `ecg-monitor` | `heartRate`, `rhythm` |


> The `data` object keys are dynamic and vary by device type and manufacturer. Always handle unknown keys gracefully.


## Confidence score

The `confidence` field is a float between `0.0` and `1.0` indicating how certain the AI is about the extraction result. A score below `0.7` may indicate a poor quality image — consider retaking the photo with better lighting and angle.

## Unsupported file type (HTTP 201, success: false)

```json
{
  "success": false,
  "message": "Unsupported file type for medical module. Supported types: JPEG, PNG, GIF, WEBP, PDF."
}
```

## Unauthorized (HTTP 401)

```json
{
  "success": false,
  "statusCode": 401,
  "path": "/v1/master?module=medical",
  "timestamp": "2026-04-02T08:26:13.716Z",
  "message": {
    "message": "Invalid API token format",
    "error": "Unauthorized",
    "statusCode": 401
  }
}
```