Overview

AI-assisted eye diagnostics over text, image and multimodal input, as clinical decision support.

Clinical decision support, not a diagnosis

Every response carries a disclaimer, and it is not decoration. Output is an AI-generated suggestion to support a clinician. A qualified clinician must review all findings and retains final decision authority. Do not build a flow that shows a prediction to a patient as a diagnosis.

The Optical Diagnostics API runs eye-condition models over three kinds of input: structured clinical text, a fundus image, or both together. It returns a predicted condition with a probability distribution, a confidence score and a treatment recommendation.

Base URL

http

https://api-diagnostics.karmat-hq.com

Interactive reference: Swagger UI · OpenAPI document

Endpoints

Method	Path	Purpose
POST	/api/v1/inference/text	Diagnose from clinical features
POST	/api/v1/inference/image	Diagnose from an eye image
POST	/api/v1/inference/multimodal	Diagnose from an image plus clinical features
GET	/api/v1/models	List available models
GET	/api/v1/analytics/usage	Request counts and latency for your key
POST	/api/v1/uploads	Store a medical image
GET	/api/v1/uploads	List your stored objects
GET	/api/v1/uploads/{object_key}/url	Mint a fresh presigned URL
DELETE	/api/v1/uploads/{object_key}	Delete a stored object
POST	/api/v1/webhooks	Register a callback URL
GET	/api/v1/webhooks	List your webhooks
DELETE	/api/v1/webhooks/{webhook_id}	Delete a webhook
GET	/health	Liveness check, no auth

Authentication

Every /api/v1/** endpoint requires an API key in the X-API-Key header. Keys are issued through the reviewed access flow described in Access and API keys.

bash

curl "https://api-diagnostics.karmat-hq.com/api/v1/models" \
  -H "X-API-Key: $DIAGNOSTICS_API_KEY"

Keys carry scopes. The default set is inference:text, inference:image, inference:multimodal, uploads:read and uploads:write. Calling an endpoint outside your scopes returns 403.

Models

The text pathway is served by an ANN-LSTM model by default. Four alternatives are selectable per request through the model field.

Model	Notes
ann-lstm	Default. Combines a dense feature encoder with a sequence model over symptom order.
ann	Feed-forward only. Fastest, and a reasonable baseline.
lstm	Sequence model alone.
gru	Gated recurrent variant, lighter than the LSTM.
xgboost-gru	Gradient-boosted trees stacked with a GRU.

Call GET /api/v1/models rather than hardcoding this list. What your key can reach is what that endpoint reports.

Sections

InferenceThe three endpoints and the diagnosis response.UploadsStore, list, re-sign and delete medical images.Webhooks and usageEvent callbacks and your request analytics.Access and API keysHow to get a key and rotate it.