Move an integration from v1 to v2
V1 remains available. Migrate individual integrations when ready using the same key and credit balance. V2 is a different request and response contract, so changing only the URL is not sufficient.
| V1 concept | V2 equivalent |
|---|---|
| Separate name, email and username endpoints | POST /api/v2/gender with type and value |
| Separate multiple endpoints | POST /api/v2/gender/batch with items |
| askToAI | options.ai_mode: fallback; single requests already default to fallback |
| forceToGenderize | Same optional field for all three types; dataset first, then nickname-aware AI |
| Flat response fields | data for the result; meta for access and billing |
| probability percentage | confidence on a 0–1 scale plus confidence_kind; AI scores are not calibrated probabilities |
| total_names | data.sample_count, nullable |
| used_credits / remaining_credits | meta.usage.charged_credits / remaining_credits |
| Legacy error format | HTTP status plus Problem Details code and action |
| POST retries | Each retry is a new operation with normal billing |
Update and verify your client
Use the v2 request and response contract for the integration you are migrating. Verify meta.access.mode, preserve JSON null results, inspect per-item batch errors and check billing before retrying. Keep v1 integrations on their existing paths until their clients have been updated.