Inference

The three inference endpoints, their inputs, and how to read a diagnosis response.

Three endpoints, one response shape. Pick the one that matches the input you actually have: a clinic with symptom notes but no camera uses text, a screening programme with a fundus camera uses image, and a full consultation uses multimodal.

Text diagnosis

POST/api/v1/inference/text

Structured clinical features in, diagnosis out. Served by the ANN-LSTM model unless model overrides it.

age

integerRequired

Patient age, 0 to 130.

symptoms

string[]Required

At least one symptom. Free text per entry. The sequence model reads their order, so record them in the order the patient reported them.

laboratory_results

object

String-to-string map of test names to results, for example {"HbA1c": "8.2%"}.

medical_history

string | null

Relevant prior conditions, as free text.

family_history

string | null

Relevant family history, as free text.

model

string | null= ann-lstm

One of ann-lstm, ann, lstm, gru, xgboost-gru.

curl -X POST "https://api-diagnostics.karmat-hq.com/api/v1/inference/text" \
  -H "X-API-Key: $DIAGNOSTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "age": 58,
    "symptoms": ["blurred vision", "floaters", "difficulty seeing at night"],
    "laboratory_results": { "HbA1c": "8.2%", "fasting_glucose": "9.1 mmol/L" },
    "medical_history": "Type 2 diabetes, 11 years",
    "family_history": "Mother had glaucoma"
  }'

Image diagnosis

POST/api/v1/inference/image

A multipart/form-data upload. The image field is the file itself; image_type describes what kind of capture it is.

image

fileRequired

The eye image, sent as a multipart file part.

image_type

string= fundus

What the capture is. Fundus is the default and the best-supported.

bash

curl -X POST "https://api-diagnostics.karmat-hq.com/api/v1/inference/image" \
  -H "X-API-Key: $DIAGNOSTICS_API_KEY" \
  -F "[email protected]" \
  -F "image_type=fundus"

Multimodal diagnosis

POST/api/v1/inference/multimodal

The strongest pathway when you have both. Note the shape: clinical_data is a JSON-encoded string carrying the same body the text endpoint takes, sent as a form field alongside the image.

image

fileRequired

The eye image, as a multipart file part.

clinical_data

stringRequired

A JSON-encoded text-diagnosis body. It is a string field, not a nested object, so encode it before sending.

bash

curl -X POST "https://api-diagnostics.karmat-hq.com/api/v1/inference/multimodal" \
  -H "X-API-Key: $DIAGNOSTICS_API_KEY" \
  -F "[email protected]" \
  -F 'clinical_data={"age":58,"symptoms":["blurred vision","floaters"]}'

Encode clinical_data, do not nest it

Sending clinical_data as a nested multipart object is the most common integration mistake here and returns 422. Run it through your language's JSON serialiser and send the resulting string.

The diagnosis response

All three endpoints return the same object.

json

{
  "prediction": {
    "condition": "diabetic_retinopathy",
    "probabilities": {
      "diabetic_retinopathy": 0.87,
      "glaucoma": 0.06,
      "cataract": 0.04,
      "normal": 0.03
    },
    "model_version": "ann-lstm-v1.2.0"
  },
  "confidence": 0.87,
  "treatment_recommendation": "Refer for dilated fundus examination within 2 weeks...",
  "explanation": "Elevated HbA1c with reported floaters and night-vision loss...",
  "image_object_key": null,
  "disclaimer": "This output is an AI-generated clinical decision-support suggestion, not a medical diagnosis. A qualified clinician must review all findings and retains final decision authority."
}

prediction.condition

string

The highest-probability condition.

prediction.probabilities

object

Every candidate condition with its probability. Read the whole distribution: a top class at 0.41 with a runner-up at 0.38 is a genuinely different clinical situation from one at 0.95.

prediction.model_version

string

The exact model build that produced this. Log it, because without it a result cannot be reproduced or audited later.

confidence

number

0 to 1, for the predicted condition.

treatment_recommendation

string

Suggested next clinical step, for the clinician to weigh.

explanation

string | null

Which input features drove the prediction. Show this to the clinician: a recommendation they cannot interrogate is one they cannot safely act on.

image_object_key

string | null

Set when the request carried an image that was stored. Use it with the uploads endpoints.

disclaimer

string

Must be surfaced wherever the result is displayed. Do not strip it.

Never auto-act on a prediction

Do not build a flow that books, refers, prescribes or discharges on the model output alone. The API is decision support: a clinician sits between the prediction and any action taken on a patient.

Errors

401

unauthorized

Missing, invalid, revoked or expired key.

403

forbidden

Your key lacks the scope for this pathway, for example inference:image on a text-only key.

422

validation_error

A field failed validation. The response body names the exact path, for example body.age above 130 or an empty symptoms array.

429

rate_limited

Read Retry-After before resending.