Response Schema

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.

---

Top-level structure

StandardAPIResponse
├── 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)

---

data — BiometryReport

Core biometry data. Always present.

data.biometer

Field	Type	Required	Values
device_name	enum	Yes	See Device names
manufacturer	enum	Yes	See Manufacturers

data.patient

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"

data.right_eye / data.left_eye — BiometricData

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)

---

extra_data — ExtraReport

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)

extra_data.posterior_keratometry

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

PosteriorKeratometryData (per eye)

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

---

metadata — ResponseMetadata

Provenance and version information. Always present.

Field	Type	Description
request_id	string	Request correlation ID for this response
schema_version	string	BiometryReport schema version (e.g., "1.0.0")
app_version	string	BiomAPI server version (e.g., "2.0.29")
extraction	PublicBiomAIMetadata | BiomDIRECTMetadata	Discriminated union — see below

metadata.extraction — discriminated union

The type is determined by method:

method value	Type	When
"BiomAI"	PublicBiomAIMetadata	Extracted from PDF or image by Gemini LLM
"BiomDIRECT"	BiomDIRECTMetadata	Manual entry, web edit, script, EHR export, or any latest-state non-LLM JSON

Common base fields (both types)

Field	Type	Description
method	"BiomAI" | "BiomDIRECT"	Discriminator
timestamp	datetime (ISO 8601)	When the extraction was performed

PublicBiomAIMetadata (additional fields)

Public BiomAI metadata includes provenance only. Internal LLM diagnostics such as token counts, retry timing, response time, and preprocessing details are omitted from API responses.

Field	Type	Description
byok	bool	true if the user supplied their own Gemini key
llm	string	Gemini model used (e.g., "gemini-3.5-flash")
input_schema_version	string | null	Schema version of the uploaded JSON on round-trip re-upload; null for fresh PDF/image extractions

BiomDIRECTMetadata (additional fields)

Field	Type	Description
input_schema_version	string	Schema version of the input payload (always populated)
source_app	string | null	Client-declared source application, such as "BiomAPI Webapp" or "BiomLINK"
source_version	string | null	Client-declared source application version

source_app and source_version are provenance fields only. They are not authentication or trust signals.

Example extraction metadata

Fresh BiomAI PDF/image extraction:

{
  "method": "BiomAI",
  "timestamp": "2025-01-15T10:30:00Z",
  "byok": false,
  "llm": "gemini-3.5-flash",
  "input_schema_version": null
}

BiomDIRECT direct/manual data:

{
  "method": "BiomDIRECT",
  "timestamp": "2026-05-24T12:00:00Z",
  "input_schema_version": "1.0.0",
  "source_app": "BiomAPI Webapp",
  "source_version": "2.0.29"
}

---

biompin — BiomPINInfo

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	BiomPIN database instance identifier

---

Enum reference

Device names

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	—

Manufacturers

"Alcon", "CSO", "HaagStreit", "Heidelberg", "Oculus", "Tomey", "Topcon", "Zeiss", "Other"

Lens status

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

Post-refractive

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

PK devices

"Anterion", "EyestarES900", "Galilei", "IOLMaster700", "MS39", "Pentacam", "Other"