4handed vision API

One endpoint for dental radiograph models. This page is the whole integration guide; it is served by the API itself, so it always matches the version that is answering. The reference below the guide describes every field.

The call

POST /v1/analyze, multipart form, header x-api-key: <your key> (keys are per customer).

curl -H "x-api-key: $KEY" -F model=m3cdt-1 -F image=@pano.png -F teeth=1,16,17,32 https://api.4handed.ai/v1/analyze

How long it takes, and retries

• About 13-16 s for four teeth.
• The first call after the service has been idle starts a fresh instance and can take 30-40 s.
• Set the client timeout to 60 s. The call is idempotent: retry once on a timeout, or on an error with retryable: true.

// Node 20: fetch, FormData and Blob are built in.
for (let attempt = 0; attempt < 2; attempt++) {
  const res = await fetch("https://api.4handed.ai/v1/analyze", { method: "POST", headers: { "x-api-key": apiKey }, body: form, signal: AbortSignal.timeout(60_000) });
  const body = await res.json();
  if (res.ok) return body;                                  // results[], skipped[], request_id, model
  if (!body.retryable) throw new Error(`${body.error}: ${body.message} (${body.request_id})`);
}

The answer

One result per third molar asked for, in request order:

{"request_id": "b7c1…", "model": "m3cdt-v1.3-2026-10-08", "image": {"status": "ok", "size": [2800, 1316]}, "min_bony_fraction": 0.02,
 "results": [{"tooth": 17, "finding": "full_bony", "crown_covered_pct": 98, "cdt_code": "D7240",
              "detail": "#17 full bony: 98% of the crown is under bone", "reason": null, "target": "numbered",
              "box": [1981.0, 628.6, 2159.5, 802.4], "overlay_png": "<base64 PNG>", "root_formation": "present",
              "position": {"winter_class": "horizontal", "winter_angle_deg": 88, "…": "see Position"}}],
 "skipped": [{"tooth": 30, "reason": "not a third molar"}]}

finding is one of four:

cdt_code is a suggestion for billing to confirm. detail is written to be shown as-is. overlay_png (base64 PNG) is the annotated crop: store it with the case. target says how the graded tooth was chosen (numbered, or last_molar when no tooth carried the number but the film showed a third molar on that side). needs_review reasons: tooth_not_found, crown_not_outlined, crown_outline_too_small. A tooth that is still forming is graded full_bony with crown_covered_pct: null and reason: developing_tooth. request_id is also the x-request-id header on every response: quote it when asking about a result.

Errors

Every error is {"error", "message", "request_id", "retryable"} with the x-request-id header.

Position

Every third molar also gets root_formation and position: where the tooth sits on the X-ray, in the classes surgeons use. Read on lower wisdom teeth (#17, #32); on uppers position is not_read for now.

"root_formation": "present",
"position": {"winter_class": "horizontal", "winter_angle_deg": 88, "pell_gregory_depth": "C", "pell_gregory_ramus": "cant_tell",
  "pederson_index": 7, "mandibular_canal": "crosses",
  "flag": "raised", "flag_because": ["pell_gregory_c", "winter_horizontal", "crosses_mandibular_canal"],
  "summary": "Horizontal (88°), Pell & Gregory position C, Pederson 7. Its outline crosses the mandibular canal's outline on the X-ray; a panoramic X-ray cannot show whether they touch.",
  "overlay_png": "<base64 PNG>"}

Every key is always present. A reading is a value, cant_tell (looked, could not tell), not_read (not looked at), or null when it does not exist for this jaw: pell_gregory_ramus, pederson_index and mandibular_canal are null on upper teeth. pederson_index is also null when winter_class or pell_gregory_depth was not read. Treat a value you do not recognise as cant_tell. pell_gregory_ramus is often cant_tell on deeply buried teeth; pederson_index then counts the ramus as class II.

These are read automatically from a panoramic X-ray. Surgeons classify by eye and disagree near class boundaries; treat the classes the same way, as a consistent first read, not a measurement.

flag is raised when the X-ray shows any of these, listed in flag_because:

• pell_gregory_c: Pell & Gregory position C, with 95% or more of the crown under bone
• winter_horizontal: Winter horizontal
• winter_distoangular: Winter distoangular, tipped back 25° or more
• crosses_mandibular_canal: the tooth's outline cuts across the mandibular canal's outline

These are the classes the published scales (Winter, Pell & Gregory, Pederson, WHARFE) score as harder, and the panoramic sign that guidelines use to suggest a 3-D scan (CBCT). not_raised: Winter, depth and the canal were all read and none applies. not_read: none applies but something could not be read. The flag cannot show whether the tooth touches the nerve; who looks at a flagged tooth is your decision.

Changes without breaking you

• New fields and values are added; existing ones keep their meaning. Ignore keys you do not use, and treat a value you do not recognise as cant_tell. A change to what raises flag is listed under What's new.
• model in every response is the exact version that answered. Send m3cdt-1 to follow the current model. Only the current version is live: a request naming an older exact id gets 404 model_not_found, so pin an exact id only if you want to be told when it changes.

What's new

• v1.3: root_formation and position on every third molar (read on lowers): Winter's class, Pell & Gregory depth and ramus class, the Pederson index, the mandibular canal, and a flag for the classes published scales score as harder. Grading unchanged. target value position renamed last_molar.
• v1.2 (2026-10-08): 16-bit greyscale PNG / TIFF exports are read correctly (they came back as "tooth not found"). When no tooth carries the referred third molar's number but the film shows a third molar on that side, the last molar there is graded; fewer needs_review results.
• v1.1 (2026-09-23): better bone edge behind upper third molars; overlay shows where the bone meets the crown.

Endpoints

Models available to this deployment

Analyze one radiograph with one model

Request: multipart/form-data

Request fields

Objects

AnalyzeResponse

ErrorResponse

ImageInfo

ModelInfo

ModelList

Position

Skipped

ToothResult