A document photo in. Structured JSON out.
The Hamdosh Document Understanding API turns a prescription, lab report, or receipt image into typed fields with per-field confidence — over one POST request. Self-hosted vision model. Nothing persisted.
- Self-hosted vision model
- Documents never persisted
- Per-field confidence
- Per-key rate limits
One request, one structured document.
Authenticate with your API key, POST an image, get back the classification, a literal transcription, and typed fields.
Request
curl -X POST 'https://medory.fly.dev:8443/understand/v1/documents' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@prescription.jpg'
Multipart upload, field name file, one image per request
(JPEG, PNG, WebP, HEIC…). The server sniffs the actual bytes — the declared
Content-Type is never trusted.
Response — 200
{
"kind": "PRESCRIPTION",
"billed": false,
"confidence": 0.87,
"transcription": "Dr. Ayesha Khan — City Care Clinic\nDx: Acute sinusitis …",
"extraction": {
"kind": "PRESCRIPTION",
"doctorName": { "value": "Dr. Ayesha Khan", "confidence": 0.95 },
"hospitalName": { "value": "City Care Clinic", "confidence": 0.92 },
"encounterDate": { "value": "2026-05-18", "confidence": 0.90 },
"diagnoses": [
{ "value": "Acute sinusitis", "icd10": "J01.90", "confidence": 0.81 }
],
"items": [
{
"medicine": "Amoxicillin",
"strength": "500 mg",
"frequency": "1 + 1 + 1",
"durationDays": 7,
"instructions": "after meals",
"confidence": 0.88
}
]
}
}What comes back.
kind
The document classification. One of:
extraction
Kind-specific structured fields — e.g. a prescription carries doctor, facility, dates,
ICD-10-coded diagnoses, and medicine line items; a lab report carries results with units,
reference ranges, and flags. Every field is { value, confidence };
unreadable or absent fields come back null with low
confidence — the model is instructed never to invent data.
transcription
The model’s literal transcription of all text it could read on the document — your ground truth for auditing the structured fields. It’s your customer’s data; we return it and keep nothing.
confidence · billed
confidence is the overall score (0–1, the mean of field
confidences) — handwriting reads lower, print reads higher.
billed tells you whether the call consumed a billable
unit or fell within your free monthly quota.
Three endpoints. That’s the API.
Base URL: https://medory.fly.dev:8443/understand/v1
POST /documents
Process one document image into structured JSON. Requires
Authorization: Bearer <api key> with the
documents:process scope. Multipart body, field
file, max 10 MB. Metered per call — free-tier
documents first, billable units after.
GET /usage
Current-period usage for the calling key — same auth as above. Periods are UTC calendar months.
{
"periodStart": "2026-06-01T00:00:00.000Z",
"periodEnd": "2026-07-01T00:00:00.000Z",
"billedDocCount": 0,
"freeDocCount": 42,
"freeMonthlyQuota": 100,
"freeRemaining": 58,
"unitPriceCents": 5,
"currency": "USD",
"costCents": 0,
"billingLive": false
} billingLive: false means exactly what it says: during
early access, usage is metered and visible here, but nothing is charged.
GET /health
Liveness probe. No auth, no document processing.
{
"service": "hamdosh-understand-api",
"status": "ok",
"vision": { "modal": true, "openaiDevFallback": false }
}When it says no.
400 Bad Request
Missing the multipart "file" part, the upload isn’t a recognized image (content is magic-byte sniffed — a spoofed Content-Type won’t pass), or the image can’t be decoded.
401 Unauthorized
Missing or malformed Authorization header, unknown key, or a revoked key. The API fails closed.
403 Forbidden
The key is valid but doesn’t carry the documents:process scope.
413 Payload Too Large
The file exceeds the upload cap (10 MB).
429 Too Many Requests
You’ve hit your key’s per-minute rate limit, or the baseline per-IP throttle (60 requests/min).
503 Service Unavailable
The self-hosted vision backend is unreachable. The API never silently falls back to a third-party provider — it surfaces the outage instead.
Rate limits are per key, set when
the key is issued, on top of a baseline per-IP throttle. Each key includes a free monthly
quota (100 documents by default); beyond it, calls are metered per document at the unit price
reported by /usage.
In flight, then gone.
- Nothing persisted. Documents are processed in flight. No bytes, no transcription, no extraction are stored — the only write is a non-PHI usage counter for metering.
- Self-hosted vision model. Extraction runs on a vision model hosted on our own infrastructure. In production there is no third-party AI API in the path — and no silent fallback to one on an outage.
- Keys are hashed, scoped, revocable. The raw key is shown once at issuance and stored only as a hash. Scopes are deny-by-default, and revocation takes effect immediately.
- HIPAA-aligned, not certified. We implement the technical safeguards and say exactly where we are — see the security page. We never claim certification we haven’t earned.
Getting a key.
API keys are issued per organization through the Hamdosh provider portal. The API is in early access — tell us what you’re building and we’ll set you up with a key and a free quota to start.
Stop hand-parsing prescriptions.
One POST request between a document photo and structured, confidence-scored JSON.