V2 to V3 Migration Guide

Timeline

Current State

API Differences

Authentication

Authentication is unchanged. Use the same x-api-key header with your existing API key. No new keys are required.

Single Image Prediction

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
}

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
}

V2 Response:

{
  "vhs": 10.2,
  "vlas": 2.8,
  "vhs_confidence": "HIGH",
  "vlas_confidence": "HIGH",
  "scores": [0.95, 0.92, 0.88, 0.91, 0.85, 0.90, 0.87, 0.83, 0.89, 0.86, 0.84],
  "landmarks": [ ... ],
  "render": "base64_rendered_image..."
}

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..."
}

New V3-Only Features

Migration Steps for B2B Customers

Minimal Migration (5 minutes)

1. Update the endpoint URL from /eu/predict to /v3/predict. The request body format is identical — image and uuid work as before.
2. Remove any unsupported parameters (extended_run, enhancement_iterations) and custom headers (X-Include-Confidence, X-Include-Bounding-Boxes, X-Enable-CLAHE, X-Disable-Rescue).

Recommended Migration

1. Complete the minimal migration above.
2. Replace vhs_confidence / vlas_confidence parsing with model_confidence (optimal / good / review).
3. Update landmark handling to expect 7 landmarks (indices 0–6) instead of 11.
4. Map your error handling to the new result_code values (0–7) and use result_description for user-facing messages.

Advanced Migration (PoP Session Flow)

1. Create a PoP session via POST /v3/pop-session/start before sending images. This enables the full Picture-of-Picture pipeline.
2. Send frames to POST /v3/pop-session with the session ID. Continue sending until session_status returns "complete" or "failed".
3. Sessions auto-expire after 5 minutes of inactivity or 20 frames.

See the V3 API Reference for complete PoP session documentation including request/response schemas.

Communication Plan

• May 8, 2026 — Migration Announcement: Email to all V2 API key holders announcing V3 availability and the V2 deprecation timeline.
• June 1, 2026 — Reminder: Follow-up email with migration progress check and a link to this guide.
• July 1, 2026 — Final Warning: Urgent notice that V2 will shut down in 30 days. Direct support offered for any remaining migrations.
• July 15, 2026 — Deprecation Headers: V2 responses will include HTTP deprecation headers to alert automated systems:

Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Deprecation: true
Link: <https://radanalyzer.com/developers/migration-guide/>; rel="deprecation"

What Happens After V2 Sunset (August 1)

• August 1: V2 service scaled to zero (still accessible via cold start as a grace period for stragglers).
• August 1–15: Grace period — any remaining V2 traffic triggers cold starts. Direct outreach to affected customers.
• August 15: V2 infrastructure fully deleted. All requests must use /v3/* endpoints.

Risks & Mitigations