Migrate from v1 to v2

Move server-side Helios traffic from v1 multipart to v2 JSON without breaking verification.

Map every v1 multipart field to its v2 JSON equivalent
Handle behavior differences like optional back image and base64 media
Roll out with dual-run, comparison, and rollback steps

Time to complete: ~15 minutes

Prerequisites

SAGEA_API_KEY set in your environment as Bearer auth.
Read Send your first API request to create a key.
Read How Helios works to compare v1 and v2 pipelines.
One working v1 integration plus sample front.jpg, back.jpg, and liveness.mp4.

Step 1: Map fields from v1 multipart to v2 JSON

v1 uses POST https://api.sagea.space/helios/kyc/v1 with multipart files. v2 uses POST https://api.sagea.space/helios/kyc/v2 with base64 JSON.

v1 multipart field	v2 JSON field	Notes
`front_image` file	`front_image_b64` string	Required in both versions
`back_image` file	`back_image_b64` string	Required in v1, optional in v2 for single sided docs
`liveness_video` file	`liveness_video_b64` string	Required, MP4 or MOV or WebM, range 3 to 10s
`external_id` text	`external_id` string	Same value, reuse to preserve user history
`callback_url` text	`callback_url` string	Same value, or set default in dashboard
none	`options` object	New in v2, use `store_media` false to minimize retention
none	`reference_portrait_b64` string	New in v2, for 1 to 1 face match

Keep external_id stable across versions so history, webhooks, and status lookups keep working.

Step 2: Send the equivalent v2 request

Translate one v1 call to v2. Auth header and response schema stay identical.

# v1 baseline
curl -X POST https://api.sagea.space/helios/kyc/v1 \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -F front_image=@"front.jpg" \
  -F back_image=@"back.jpg" \
  -F liveness_video=@"liveness.mp4" \
  -F external_id="user_12345"
 
# v2 equivalent
curl -X POST https://api.sagea.space/helios/kyc/v2 \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"user_12345","front_image_b64":"BASE64_FRONT","back_image_b64":"BASE64_BACK","liveness_video_b64":"BASE64_VIDEO","options":{"store_media":false}}'

Behavior differences: v2 accepts single-sided IDs without back_image_b64, expects base64 (about 33 percent larger payloads), and supports store_media false for privacy.

Step 3: Roll out with dual-run and rollback

Ship v2 behind a flag, compare decisions, then cut over fully.

curl https://api.sagea.space/helios/verifications/helios_vrf_9f3a2c1e \
  -H "Authorization: Bearer $SAGEA_API_KEY"

Rollout checklist: shadow 10 percent, alert on decision mismatch, verify verification_id storage still works, confirm callback_url delivery, then promote to 100 percent and deprecate v1 code.

Verify

Both versions return HTTP 200 with identical schema: verification_id, decision, scores, reasons, extracted, and model_used. If migration fails, check below.

Error	Cause	Fix
`401 Unauthorized`	API key missing or invalid	Confirm `echo $SAGEA_API_KEY` is set and retry
`400 missing_artifact`	Base64 field misnamed or empty	Use `front_image_b64` and `liveness_video_b64` keys
`413 Payload Too Large`	Base64 video exceeds about 50MB	Compress source video before encoding
`422 spoof_detected`	Recaptured media flagged as spoof	Reuse original test media to isolate encoding bugs