All successful responses from POST /api/v1/biom/process and GET /api/v1/biom/retrieve return a StandardAPIResponse object with four top-level fields.
For annotated examples, see the Swagger UI at /apidocs.
├── data: BiometryReport (always present)
├── extra_data: ExtraReport | null (present for PK-capable devices)
├── metadata: ResponseMetadata (always present)
└── biompin: BiomPINInfo | null (present when BiomPIN was requested)
Core biometry data. Always present.
All patient fields are optional — they may be null if not present in the source file.
| Field | Type | Description |
|---|
name | string | null | Automatically converted to all-caps initials for privacy (e.g., "John Douglas Doe" → "JDD") |
id | string | null | Patient ID or medical record number |
date_of_birth | date (ISO 8601) | null | e.g., "1965-03-15" |
gender | enum | null | "Male" or "Female" |
All measurement fields are optional (null if not measurable or not present in the source).
| Field | Unit | Valid range | Description |
|---|
AL | mm | 14 – 40 | Axial length |
ACD | mm | 1 – 6 | Anterior chamber depth |
K1_magnitude | D | 20 – 99 | Flat keratometry power |
K1_axis | ° | 0 – 180 | K1 axis |
K2_magnitude | D | 20 – 99 | Steep keratometry power |
K2_axis | ° | 0 – 180 | K2 axis |
WTW | mm | 7 – 15 | White-to-white corneal diameter |
LT | mm | 0.1 – 7 | Crystalline lens thickness |
CCT | µm | 200 – 900 | Central corneal thickness |
lens_status | enum | null | — | See Lens status |
post_refractive | enum | null | — | See Post-refractive |
keratometric_index | — | 1.330 – 1.338 | Index of refraction used for keratometry conversion (typically 1.3375) |
Optional additional data. null for devices that don’t support posterior keratometry extraction.
| Field | Type | Description |
|---|
notes | string | null | Clinical notes or free-text annotations |
posterior_keratometry | PosteriorKeratometry | null | PK measurements (device-dependent) |
Present only for devices that support PK extraction: Anterion, EyestarES900, IOLMaster700, MS39, PentacamAXL.
| Field | Type | Description |
|---|
pk_device_name | enum | null | Source device for PK measurement — see PK devices |
right_eye | PosteriorKeratometryData | Right eye PK measurements |
left_eye | PosteriorKeratometryData | Left eye PK measurements |
| Field | Unit | Valid range | Description |
|---|
PK1_magnitude | D | 2 – 8 | Posterior flat keratometry power |
PK1_axis | ° | 0 – 180 | PK1 axis |
PK2_magnitude | D | 2 – 8 | Posterior steep keratometry power |
PK2_axis | ° | 0 – 180 | PK2 axis |
Provenance and version information. Always present.
| Field | Type | Description |
|---|
schema_version | string | BiometryReport schema version (e.g., "1.0.0") |
app_version | string | BiomAPI server version (e.g., "0.9.8.1") |
extraction | BiomAIMetadata | BiomDIRECTMetadata | Discriminated union — see below |
The type is determined by method:
method value | Type | When |
|---|
"BiomAI" | BiomAIMetadata | Extracted from PDF or image by Gemini LLM |
"BiomDIRECT" | BiomDIRECTMetadata | Manual entry, script, EHR export, or any non-LLM JSON |
| Field | Type | Description |
|---|
method | "BiomAI" | "BiomDIRECT" | Discriminator |
timestamp | datetime (ISO 8601) | When the extraction was performed |
filename | string | null | Original filename of the uploaded file |
| Field | Type | Description |
|---|
byok | bool | true if the user supplied their own Gemini key |
llm | string | Gemini model used (e.g., "gemini-flash-latest") |
llm_api_metrics | LLMApiUsageMetrics | null | Token usage from the Gemini API |
llm_performance | LLMPerformanceMetrics | Timing and retry counts |
input_schema_version | string | null | Schema version of the uploaded JSON on round-trip re-upload; null for fresh PDF/image extractions |
| Field | Type | Description |
|---|
prompt_token_count | int | null | Total input tokens (includes cached) |
cached_content_token_count | int | null | Tokens served from cache |
candidates_token_count | int | null | Output tokens generated |
thoughts_token_count | int | null | Internal thinking tokens (if thinking enabled) |
total_token_count | int | null | Sum of all tokens |
cache_hit_ratio | float (0–1) | null | Cached / total prompt tokens |
| Field | Type | Description |
|---|
llm_response_time_seconds | float | Time for the Gemini API call (seconds) |
retry_attempts | int | Number of retries due to 429/503 |
total_retry_delay_seconds | float | Total wait time spent on retries |
| Field | Type | Description |
|---|
input_schema_version | string | Schema version of the input payload (always populated) |
Present when a BiomPIN was generated (biompin=true in the request). null otherwise.
| Field | Type | Description |
|---|
pin | string | Full PIN code: word-word-123456 |
expires_at | string (ISO 8601) | When the PIN expires (default: 31 days from creation) |
db_id | string | Database instance identifier — use to detect stale history entries |
| Value | Device | Manufacturer |
|---|
"Aladdin" | Aladdin | Topcon |
"Anterion" | Anterion | Heidelberg |
"Argos" | Argos | Alcon |
"IOLMaster700" | IOLMaster 700 | Zeiss |
"LenstarLS900" | Lenstar LS 900 | HaagStreit |
"EyestarES900" | Eyestar ES 900 | HaagStreit |
"MS39" | MS-39 | CSO |
"OA-2000" | OA-2000 | Tomey |
"PentacamAXL" | Pentacam AXL | Oculus |
"Other" | Unrecognized device | — |
"Alcon", "CSO", "HaagStreit", "Heidelberg", "Oculus", "Tomey", "Topcon", "Zeiss", "Other"
| Value | Description |
|---|
"Phakic" | Natural crystalline lens present |
"Phakic IOL" | Natural lens present with an additional phakic IOL |
"Pseudophakic" | Natural lens replaced with IOL |
"Aphakic" | No lens present |
| Value | Description |
|---|
"None" | No prior refractive surgery |
"Myopic LVC" | Myopic laser vision correction (LASIK, PRK, LASEK) |
"Hyperopic LVC" | Hyperopic laser vision correction |
"Radial Keratotomy" | Radial keratotomy |
"Anterion", "EyestarES900", "Galilei", "IOLMaster700", "MS39", "Pentacam", "Other"