What a Biomarker API Should Return to Build a Trustworthy Health Product

Model laboratory observations before scoring them

Choose whether your product needs raw measurement storage, interpretation, calculated metrics, trends, or all four. Blending those layers into one opaque score makes it difficult for users and support teams to understand why a dashboard changed.

Normalize carefully and preserve the original report

Ingest the original source and preserve the reported marker name, value, unit, collection date, and laboratory context. Normalize aliases and units carefully and retain a link to the original. Calculate derived metrics as separate outputs that cite the direct results used.

Return structured data a frontend can render: value, unit, target policy, status, confidence, sources, and a plain-language summary. Recommendations should match the product's safety policy and state the limits of the information.

A minimal observation schema

Store an immutable source reference, original analyte label, normalized concept, numeric or textual value, original and normalized units, collection time, laboratory, specimen where available, reference interval, flags, and parse confidence. Preserve unparsed lines and the source report for review.

Derived metrics need their own identifiers, formulas, source observation IDs, method version, and calculation time. Never overwrite the direct measurements used by the formula.

Return useful errors to product teams

A 400 response should say which field, unit, date, or file area failed and whether the client can fix it. Partial imports should return accepted rows and rejected rows with reasons. Duplicate submissions need an idempotency path.

Include request identifiers and stable error codes. REST clients and MCP agents can use the same codes to show a fix, retry safely, or route the report for manual review.

• unsupported_unit
• missing_collection_date
• ambiguous_marker
• partial_parse
• duplicate_source

Biomarker API acceptance criteria

• Original and normalized values are both recoverable
• Derived metrics cite every source observation
• Reference intervals remain source-specific
• Partial parsing is explicit
• Trend queries preserve dates, units, and method context
• Every user-facing card links back to source provenance

Return render-ready biomarker objects

WellNizz imports biomarker data from CSV, JSON, plain text, and supported PDFs; derives metrics; runs analysis; returns trends and action priorities; and produces renderer-neutral dashboard specifications. The design keeps direct and derived biomarker outputs distinct so a product can explain both.

Keep interpretation policy visible and versioned

Reference ranges and target policies are not one-size-fits-all medical instructions. Keep source data visible, avoid diagnostic claims, and build a clinician escalation path for high-stakes findings.