3.25 → 3.29

The 3.25 → 3.29 transition is additive — no payload field that existed in 3.25.0 changes shape or disappears. New components and a new status code arrive; one visualisation scale shifts.

TL;DR

• Three new components you may want to opt into: skin_age (already documented in 3.25), skin_type, hyperpigmentation_adjusted.
• One new status code: 99 (custom-context, undefined failure).
• The acne_visualization intensity range widened. If your UI clamps to a hard-coded ceiling, raise it.
• Treat local_warnings[] codes as advisory, not contractual: render whatever findings come back, hide the cards that don’t.

Step by step

1. Update the spec reference

If you generate clients from the OpenAPI document, point your generator at the new spec:

• Live URL: https://api.revieve.com/openapi/skin-analysis.yaml
• Or pin to a commit in this repo.

2. Handle the new status code

Add 99 to your status-code map. Treat it as transient and offer the user a retry, the same way you’d handle a 5xx.

const FATAL_CODES = new Set([100, 101, 102, 201, 206, 99]);

3. Opt into new components (optional)

Add to your components query string only what your UI surfaces:

?components=wrinkles,redness,acne,hyperpigmentation
?components=wrinkles,redness,acne,hyperpigmentation,hyperpigmentation_adjusted,skin_age,skin_type

Each new component adds work for the model. Don’t request what you don’t render.

4. Adjust visualization rendering

The acne_visualization intensity values are no longer clipped to the previous ceiling. If your renderer normalises intensities, update the divisor; if it clamps to a fixed max, raise that max or switch to acne_normalized_visualization.

5. Code defensively against local_warnings[]

The local_warnings[] array is advisory, not a stable contract. Render whatever findings come back; hide the cards whose local_warnings[] indicates an unusable result for that metric. Don’t hard-fail the whole UI on any specific code.

What hasn’t changed

• The endpoint path and authentication model.
• The image requirements (JPEG, ≥ 600×600).
• The shape of face_area, top-level status, and inverse_color_balance_rb.
• The value normalisation (0..1) on numeric findings.
• The deprecation of value_raw.

Rollback

Set your client back to the 3.25.0 spec. The 3.29 server remains compatible with 3.25-shaped requests; newer components won’t appear in the response.