StructaMed Partner API v1

Send structured laboratory results, receive a rule-based interpretation. The analysis is deterministic and rule-based: no AI model is called, and nothing you send is used for any purpose other than producing the response.

This is an interpretation aid for clinicians and laboratory staff. It does not replace clinical judgement, and it makes no diagnosis.

Machine-readable spec (OpenAPI 3.1): https://<host>/partner/openapi.yaml. A Postman collection is at https://<host>/partner/structamed-partner.postman_collection.json (set the variables baseUrl and apiKey). This reference is also published at https://<host>/labs/api. A step-by-step setup guide for your IT team is available on request.

Endpoint

POST https://<host>/api/v1/analyze
Content-Type: application/json

Authentication

Send your key in either header:

Authorization: Bearer sm_live_<32 characters>
x-api-key: sm_live_<32 characters>

Keys are issued to you once. Only a hash is stored on our side, so a lost key cannot be recovered, only replaced. A missing, unknown or deactivated key returns 401.

Request

{
  "patient": { "sex": "male", "age": 45, "birth_date": "1980-01-31" },
  "collected_at": "2026-09-30",
  "mode": "clinical",
  "lang": "en",
  "results": [
    { "name": "ApoB", "code": "optional", "value": 1.32, "unit": "g/L",
      "ref_low": 0.6, "ref_high": 1.0, "ref_text": "optional printed range", "flag": "H" }
  ],
  "previous": [
    { "collected_at": "2025-09-30", "results": [ { "name": "ApoB", "value": 1.1, "unit": "g/L" } ] }
  ]
}

Maximum body size: 1 MB.

Response (200)

{
  "request_id": "req_...",
  "engine_version": "structamed-engine/2026-10",
  "lang": "en",
  "summary": "Some findings are outside the optimal range and worth reviewing.",
  "summary_code": "summary.wellness_findings_present",
  "risk": { "score": 1.4, "level": "low" },
  "counts": { "received": 19, "graded": 19, "abnormal": 4 },
  "findings": [ ... ],
  "patterns": [ { "type": "anemia", "confidence": "moderate", "evidence": ["..."] } ],
  "clusters": ["metabolic"],
  "notes": [ { "key": "notes.lipid_abnormal", "text": "..." } ],
  "next_steps": { "urgency": "routine", "steps": [ { "category": "monitor", "key": "...", "text": "...", "confidence": "moderate" } ] },
  "unrecognized": [ { "name": "Xyz", "value": 3, "unit": "u", "reason": "marker name is not recognized" } ],
  "trends": [ ... ],
  "trends_skipped": [ { "key": "ferritin", "reason": "unit differs between panels; not compared" } ]
}

trends and trends_skipped appear only when previous was sent.

findings[]

One entry per graded marker, normal ones included.

trends[]

Per marker present in both the current panel and at least one earlier panel with the same unit: points (oldest first, the current panel last), direction (up/down/flat, flat being under 5% movement), quality (improving, worsening, mixed, stable, judged by distance to the range, not by the sign of the change), first, last, change_percent, notable_change (true when the value moved by 25% or more between the first and last point, whatever quality says: a marker can be stable because it stays inside its range and still have fallen by 40%; the flag never changes quality, direction or out_of_range). Trend values are the numbers as you sent them, in your unit. A marker whose unit differs between panels is listed in trends_skipped, never converted silently.

warnings[]

Top-level list of plain-text notes, present only when there is something to say. Today: a row whose LOINC code and name disagree (for example the code is a urine test and the name says serum). The code wins; the warning tells you so you can fix the source.

unrecognized[]

Nothing is dropped silently. A row appears here if its name is not a known marker, if it duplicates another row for the same marker (the first one is analyzed), if the engine rejected its unit or value as impossible for that marker, or if it was recognized but could not be graded. A finding is only as good as the name matching: please review this list.

recognition

An answer carries a recognition block when it has something to report (a row nothing recognised, or a row your dictionary resolved); POST /api/v1/recognize always returns it. The block holds total_rows, by_source (partner_dictionary, code, global, none), no_value (rows without a result value) and unresolved[] with the reason and up to three closest catalog entries per row (suggestions, hints only, never applied). POST /api/v1/recognize takes the same key and body as /api/v1/analyze and returns only this block (plus unit warnings and omics notes); it runs no analysis, makes no AI call, renders no PDF and is not counted as a report. Rows your account's dictionary maps carry matched_by: "partner_dictionary" in findings[].

collection

results[] and omics.functional[] rows accept an optional collection object: specimen, time_point, fasting (boolean), provoked (boolean), provoking_agent and collected_at (date or ISO date-time). Explicit fields win over what is inferred from the printed name; provoked: false overrides any provocation wording. Unknown fields or wrong types are refused with 400 and a message naming the field.

LOINC codes

Send the LOINC code in results[].code when your system has it. Precedence:

1. A supported code decides the marker (matched_by: "loinc"). Your name is not used to route; it is still returned as input_name.
2. An unknown or absent code falls back to the name (matched_by: "name"). Nothing is rejected for an unknown code.
3. If a supported code and the name point at different markers, or at different specimens (urine against serum), the code wins and an entry is added to warnings[].

Specimens are separate markers: urine creatinine and serum creatinine, urine albumin and serum albumin never map to each other. Mass and molar codes of one analyte (for example LDL 13457-7 in mg/dL and 22748-8 in mmol/L) map to the same marker; send the unit that goes with your value and it is converted.

The supported list (code, marker key, specimen, usual unit, LOINC name, verification date) is served as JSON by GET /api/v1/loinc: no key needed, 30 requests per minute per client address.

Values, units and ranges

What the API accepts, as tested against a corpus of South-East Asian and Australian LIS-style rows.

Marker names. Case, British spellings, a glued flag or star (ALT (SGPT) *, Glucose (H)), and specimen words (Serum Urea, Ferritin, Serum, PSA, Plasma) are handled; so are common LIS labels such as FPG, Alk Phos, Gamma GT, Total White Cell Count, Mean Cell Volume, Total CO2, Lipoprotein (a). Two labels are refused on purpose, with a reason in unrecognized: post-prandial glucose (it has no fasting range) and bioavailable testosterone (it is not total testosterone). A LOINC code in code overrides the name.

Values.

A thousands separator is not guessed: "1,234" is read as 1234 (a decimal comma is only assumed when there is no group of three digits after it). Send plain numbers if your system prints comma decimals with three decimals.

Units. Case and the micro sign are levelled (umol/L, µmol/L, μmol/L; MMOL/L). Counts may be x10^9/L, 10^9/L, x10E9/L, K/uL, x10^3/uL, 10*3/uL (and /uL for WBC and platelets, which is divided by 1000). A method note in the unit is dropped (mmol/mol (IFCC), % (NGSP)). Values in conventional and SI units are converted to the engine's unit and the original is returned in submitted. Lipoprotein(a): mg/dL is native, g/L and mg/L are converted; nmol/L is never converted (the ratio to mg/dL depends on the assay): the value is kept in nmol/L and, if you sent no reference range, it is graded against a molar default of ours, < 75 nmol/L (EAS 2022 consensus: < 75 nmol/L (30 mg/dL) low risk, 75-125 grey zone, > 125 nmol/L (50 mg/dL) high risk), with ref_source: "engine_default" and a warning that says so. Your own ref_low/ref_high win.

Reference ranges. ref_low/ref_high or ref_text (3.5 - 5.1, 3.5-5.1, 3.5 to 5.1, 0.6–1.0, <5.2, <= 5.2, > 1.0, ≥1.0, Desirable: <5.2, several risk-tier lines, Male: 59-104 Female: 45-84, Age 18-60: 59-104 / Age >60: 50-110) are read for the patient's sex and age; for tiers the "desirable" tier is the range. A range with ref_low greater than ref_high is rejected with 400. A range in a unit other than the value's: if the text names the unit (53-106 umol/L) it is converted; if it does not and the numbers do not fit the value's unit but fit another known unit of the marker (creatinine 0.6-1.2 beside a value in µmol/L), it is read in that unit and a warnings[] entry says so; if it fits no known unit it is set aside, the engine's default range is used (ref_source: "engine_default") and a warning says so.

Panels. 1-300 rows (301 gives 400). Two rows for the same marker (for example mg/dL and mmol/L): the first is always the one graded. If the later row agrees with it (within 10 % after unit conversion) it is listed in unrecognized as a duplicate. If it disagrees, both rows are listed in unrecognized with the reason conflicting duplicate, so the conflict is visible; the first is still the one graded. In previous, a unit spelled differently (umol/L and µmol/L) is the same unit; a really different unit (mg/dL against µmol/L) is left out of trends and listed in trends_skipped.

Patient context

patient.context is optional. Unknown fields or values and contradictions (pregnancy or menopausal status for male, a trimester without pregnant: true) return 400. Whatever you send is answered in two top-level lists, present only when patient.context was sent: context_applied (what changed the analysis) and context_ignored (accepted, but the engine has no rule for it, with the reason). Nothing is pretended: a field that is not wired is never listed as applied.

"context": {
  "athlete": true,
  "menopausal_status": "pre | peri | post",
  "pregnant": true, "trimester": 2,
  "fasting": true,
  "medications": ["statin", "levothyroxine", "testosterone", "biotin", "metformin", "oral_contraceptive", "glp1"],
  "conditions": ["type2_diabetes", "hypothyroidism", "ckd", "heart_failure"],
  "setting": "outpatient | acute",
  "smoker": true
}

Each context_applied entry: { "field", "value", "effect", "affected_markers": [...] }. affected_markers are the markers of THIS panel the rule can act on; an empty list means the rule is on but nothing in the panel is subject to it. Each context_ignored entry: { "field", "value", "reason" }.

Serial troponin

When the panel has a troponin (troponin = hs-cTnT, or troponin_i) and a previous panel carries the same marker, the change is judged and the verdict is added to the finding's rationale (codes rationale.troponinRise01h, troponinRise02h, troponinRiseRelative, troponinRiseNoInterval, troponinNoRise, troponinNoRiseNoInterval, with values: from, to, delta, percent, hours, p99). The nearest earlier panel is used; values are compared in the engine's unit (ng/L).

A rise is graded critical (acute myocardial injury until proven otherwise), the case is urgent, and the emergency work-up stays even with setting: "outpatient". A change below the thresholds does not raise the severity; the rationale says so, and that a stable raised value points to chronic injury (the clinical picture and ECG decide). The interval is unknown when either time stamp has no time of day (date only, including two panels on the same day), or when one has a UTC offset and the other does not; then only the relative rule is applied and the rationale says that the 0/1-h and 0/2-h rules need collected_at with a time. A falling troponin is not a rise.

Lipid and tumour-marker next steps

Added to next_steps.steps (all worded as a work-up, never as a diagnosis; clinical mode only for the tumour markers):

Errors

Every error is JSON: { "error": { "code": "...", "message": "...", "request_id": "..." } }.

Limits and metering

• 300 results per request, 12 previous panels, 1 MB body.
• 30 requests per minute per key (counted per server instance).
• One successful (HTTP 200) call counts as one report, on /api/v1/analyze or /api/v1/report. Failed calls are not counted.

Branded PDF report

POST https://<host>/api/v1/report
Content-Type: application/json

Same authentication, request body, validation, limits and errors as /api/v1/analyze, and the same rule-based analysis (no AI model is called). The response is 200 application/pdf instead of JSON: a report your clinicians can read, in your branding. Two optional fields are added:

lang selects the language of the PDF (as for analyze); when absent your profile's default is used. Errors are the same JSON error objects as for analyze; a failed render returns 500 internal_error.

One successful call is one metered report. A report call is not also counted as an analyze call.

Your profile

The look of your PDF is set per partner by us; it is not sent with each request. Fields:

Without a profile you get the defaults: StructaMed palette and branding, English, blocks.

The line "Structured for clinical review. Final judgment remains with the clinician." (translated) is a safety statement and is printed on every report, whatever the profile says.

Example

curl -s https://<host>/api/v1/analyze \
  -H "Authorization: Bearer $STRUCTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patient": { "sex": "male", "age": 45 },
    "results": [
      { "name": "ApoB", "value": 1.32, "unit": "g/L", "ref_low": 0.6, "ref_high": 1.0 },
      { "name": "ALT", "value": 22, "unit": "U/L", "ref_high": 50 }
    ]
  }'

Glossary

• Reference range: the interval a laboratory prints as expected for a healthy population. Yours win over our defaults when sent.
• Status: where the value sits relative to the range used (low/normal/high).
• Severity: how much attention the finding deserves (info, warning, critical).
• Pattern: a combination of markers that together suggest a recognized picture (for example iron-deficiency anemia). Patterns are suggestions for review, not diagnoses.
• Cluster: the body system a group of findings belongs to.
• Risk: a coarse overall level (low, medium, high) with a numeric score derived from the findings; useful for sorting, not for diagnosis.