V2 to V3 Breaking Changes

Architecture Changes

Breaking Changes

1. Endpoint URL

The base path changes from /eu/predict to /v3/predict.

- POST https://api.radanalyzer.com/eu/predict
+ POST https://api.radanalyzer.com/v3/predict

2. Confidence Tier Names

V2 returned separate vhs_confidence and vlas_confidence fields with values HIGH, MEDIUM, or LOW. V3 returns a single model_confidence field with values optimal, good, or review.

3. Removed Response Fields

The following fields are no longer present in V3 responses:

4. Result Codes Redesigned

V3 introduces a new set of numeric result codes (0–7) that replace V2's error handling:

5. Server-Side Rendering Parameter

The parameter to request a rendered overlay image has been renamed:

- "include_render": true
+ "render": true

6. Health Check Endpoint

The health check endpoint has changed:

- GET https://api.radanalyzer.com/eu/health
+ GET https://api.radanalyzer.com/v3/health

Non-Breaking Changes

The following fields are new in V3 responses. They are additive and do not affect existing integrations:

New V3-Only Features

Migration Checklist

Minimal migration (5 minutes)

• Update the endpoint URL from /eu/predict to /v3/predict
• Update health check URL from /eu/health to /v3/health
• Remove extended_run and enhancement_iterations from request bodies
• Remove custom headers (X-Include-Confidence, X-Include-Bounding-Boxes, X-Enable-CLAHE, X-Disable-Rescue)

If you parse confidence tiers

• Replace vhs_confidence / vlas_confidence with model_confidence
• Update tier value comparisons: HIGH → optimal, MEDIUM → good, LOW → review

If you use landmark coordinates

• Update any code referencing landmarks by index — V3 only returns indices 0–6
• Remove references to any V2-only auxiliary landmarks
• Verify that your rendering logic handles 7 landmarks instead of 11

If you use server-side rendering

• Rename include_render to render in your request body
• The response field is rendered_image (base64 PNG) — unchanged from V2

If you use result_code

• Map your error handling to the new result codes (0–7)
• Add handling for new codes: 4 (VHS predicted, VLAS could not be calculated), 5 (neither VHS nor VLAS could be calculated), 7 (PoP perspective correction failed)
• Use result_description for user-facing messages

Timeline

Side-by-Side Examples

V2 Request

POST /eu/predict HTTP/1.1
Host: api.radanalyzer.com
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "image": "base64_encoded_image_data...",
  "uuid": "patient-123",
  "include_render": true,
  "extended_run": true,
  "enhancement_iterations": 3
}

V2 Response

{
  "vhs": 10.2,
  "vlas": 2.8,
  "vhs_confidence": "HIGH",
  "vlas_confidence": "HIGH",
  "scores": {
    "vhs_ebm": 0.92,
    "vlas_ebm": 0.88
  },
  "landmarks": [ ... ],
  "render": "base64_rendered_image..."
}

V3 Request

POST /v3/predict HTTP/1.1
Host: api.radanalyzer.com
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "image": "base64_encoded_image_data...",
  "uuid": "patient-123",
  "render": true
}

V3 Response

{
  "vhs": 10.2,
  "vlas": 2.8,
  "model_confidence": "optimal",
  "spread": 0.003,
  "pop_detected": false,
  "model_version": "v3.3.0",
  "result_code": 1,
  "result_description": "VHS and VLAS predicted successfully with high confidence.",
  "landmarks": [
    { "x": 0.42, "y": 0.15, "class": "heart_top" },
    { "x": 0.41, "y": 0.44, "class": "heart_bottom" },
    { "x": 0.25, "y": 0.30, "class": "heart_right" },
    { "x": 0.57, "y": 0.29, "class": "heart_left" },
    { "x": 0.49, "y": 0.40, "class": "VLAS" },
    { "x": 0.36, "y": 0.12, "class": "Vertebra A" },
    { "x": 0.55, "y": 0.12, "class": "Vertebra B" }
  ],
  "rendered_image": "base64_rendered_image..."
}