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.

Creating JSON for BiomDIRECT? Follow JSON input / BiomDIRECT for the upload requirements. This page describes the completed output. Fields such as metadata are always present in the response, but you can omit them from input.

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

Start with the complete synthetic response, or explore the API in Swagger UI.

---

Top-level structure

StandardAPIResponse
├── data: BiometryReport                (always present)
├── extra_data: ExtraReport | null      (optional notes, posterior or total keratometry)
├── metadata: ResponseMetadata          (always present)
└── biompin: BiomPINInfo | null         (present when a share was created)

---

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 examination date in ISO 8601 format (YYYY-MM-DD). It applies to the report and is separate from data.patient.date_of_birth. If no examination date is available, the value is null.

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

Both eye objects are required, but their measurement fields are optional. Use an empty object for an eye with no supplied data; the response fills its fields with null. A missing measurement is not zero or a normal finding. Validation ranges describe accepted input, not clinical reference ranges.

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 (integer)	K1 axis
K2_magnitude	D	20 – 99	Steep keratometry power
K2_axis	°	0 – 180 (integer)	K2 axis
WTW	mm	7 – 17	White-to-white corneal diameter
LT	mm	0.1 – 7	Crystalline lens thickness
CCT	µm	200 – 900 (integer)	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)

For JSON uploads and manual edits, these rules apply:

• If you supply both K magnitudes, K1_magnitude ≤ K2_magnitude is required.
• If you supply both axes, they must differ by exactly 90°.
• Partial sets are accepted, including magnitudes without axes.

Inconsistent pairs return HTTP 422 with validation details for each affected field. BiomAPI does not swap or infer measurements.

BiomAI retains its stricter extraction guard: incomplete or inconsistent anterior K sets are cleared, after any supported device-specific correction.

---

extra_data — ExtraReport

Optional notes and keratometry measurements. BiomAI extracts explicitly printed PK and TK from IOLMaster700 reports only. JSON input and manual measurements can supply PK from other devices, while TK requires IOLMaster700 as its source. Older JSON files may omit extra_data or any TK fields.

Field	Type	Description
notes	string | null	Clinical notes or free-text annotations
posterior_keratometry	PosteriorKeratometry | null	PK and TK measurements; either group may be absent

extra_data.posterior_keratometry

This property contains both posterior keratometry (PK) and total keratometry (TK). Each eye can contain PK, TK, both, or neither.

pk_device_name identifies their shared source independently of data.biometer. TK values require IOLMaster700 as the source. PK values do not. See PK devices.

Field	Type	Description
pk_device_name	enum | null	Shared source device for PK and TK measurements — see PK devices
right_eye	PosteriorKeratometryData	Right eye PK/TK measurements
left_eye	PosteriorKeratometryData	Left eye PK/TK measurements

A TK-only extra_data fragment in a complete JSON input is valid:

{
  "extra_data": {
    "posterior_keratometry": {
      "pk_device_name": "IOLMaster700",
      "right_eye": {
        "TK1_magnitude": 43.25,
        "TK1_axis": 5,
        "TK2_magnitude": 44.5,
        "TK2_axis": 95
      },
      "left_eye": {}
    }
  }
}

Per-eye PK and TK measurements

The same per-eye object holds both sets of optional measurements.

Posterior keratometry (PK)

Field	Unit	Valid range	Description
PK1_magnitude	D	2 – 10	Posterior flat keratometry power
PK1_axis	°	0 – 180 (integer)	PK1 axis
PK2_magnitude	D	2 – 10	Posterior steep keratometry power
PK2_axis	°	0 – 180 (integer)	PK2 axis

You can supply PK powers with either sign. BiomAPI converts them to positive magnitudes, then checks the 2–10 D range. Newly processed responses, BiomPIN shares, and exports contain positive magnitudes. For example, -6.1 and -6.5 become 6.1 and 6.5.

Total keratometry (TK)

Field	Unit	Valid range	Description
TK1_magnitude	D	20 – 99	Total flat keratometry power
TK1_axis	°	0 – 180 (integer)	TK1 axis
TK2_magnitude	D	20 – 99	Total steep keratometry power
TK2_axis	°	0 – 180 (integer)	TK2 axis

Validation and extraction

For JSON uploads and manual edits, these rules apply to each PK or TK pair:

• Powers must follow abs(PK1_magnitude) ≤ abs(PK2_magnitude) or TK1_magnitude ≤ TK2_magnitude.
• If you supply both axes, they must differ by exactly 90°.
• Partial pairs and equal powers are accepted.

BiomAPI does not infer missing measurements. Inconsistent pairs return HTTP 422.

BiomAI uses stricter extraction checks. Each PK or TK pair must have both powers and both axes. Powers must be ordered, and axes must be 90° apart.

BiomAI clears each invalid or incomplete pair separately. It keeps otherwise valid core biometry. These checks do not change JSON or manual-input validation.

---

metadata — ResponseMetadata

Provenance and version information. Always present.

Field	Type	Description
request_id	string	Request correlation ID for this response; retrieval assigns a new ID
schema_version	string	Report schema version (currently "1.1.0")
app_version	string	BiomAPI server version (e.g., "2.2.15")
extraction	PublicBiomAIMetadata | BiomDIRECTMetadata	Discriminated union — see below

metadata.extraction — discriminated union

method determines the metadata type. Uploaded metadata declares provenance, which records the source of the data. It does not prove that a downloaded file is unchanged. Web-app edits set method to BiomDIRECT.

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.8-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": "2026-09-05T10:00:00Z",
  "byok": false,
  "llm": "gemini-3.8-flash",
  "input_schema_version": null
}

BiomDIRECT direct/manual data:

{
  "method": "BiomDIRECT",
  "timestamp": "2026-09-05T10:00:00Z",
  "input_schema_version": "1.0.0",
  "source_app": "BiomAPI Webapp",
  "source_version": "2.2.15"
}

---

biompin — BiomPINInfo

Contains BiomPIN details when sharing succeeds. If sharing is unavailable, it can be null even when you requested biompin=true. Check for a PIN before using it.

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"