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.

Other endpoints use their own response formats, documented in the REST API reference.

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.exam_date`

Optional ISO 8601 date (YYYY-MM-DD) for when the biometry examination was performed. This is report-level information and is separate from data.patient.date_of_birth; it is null when no exam date is available.

`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 – 17	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.1.66"`)
`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.7-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.7-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.1.66"
}

`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"

Response Schema

Top-level structure

data — BiometryReport

data.biometer

data.exam_date

data.patient

data.right_eye / data.left_eye — BiometricData

extra_data — ExtraReport

extra_data.posterior_keratometry