Engine versions and opting in
The calculation engine has versions. Each cobrand uses one version, and its results don't change until a customer admin chooses a newer one. You can always tell which version produced a result.
Before you start
You don't choose a version in a request. The version belongs to your cobrand, and the API addresses are the same for every version. The v1 in /v1/calculators is the version of the API contract, not of the engine.
How versions work
- Pinned to your cobrand. Your cobrand has one engine version, a whole number such as
1. The REST API, the embed endpoints and the MCP endpoint all use it. Hosted pages load their calculators through the embed endpoints, so they use it too. - Side by side. A new engine version ships next to the old ones. Your integration stays on its version until you opt in. A calculation update never changes a live integration by itself.
- Forward only. A customer admin opts in on the Engine version page in the portal. The page lists released versions newer than yours. You can't move to an older version or to one that isn't released.
- Supported. Older versions keep working with no end date at launch. We haven't decided on a deprecation window. The docs will say when that changes.
Minimal example
Every calculation response names the version that produced it:
export AZTEC_API_HOST="<your API host>"
export AZTEC_SECRET_KEY="<your secret key>"
curl -sS -i -X POST "https://$AZTEC_API_HOST/v1/calculators/auto-loan-payment/calculate" \
-H "Authorization: Bearer $AZTEC_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs":{"vehiclePrice":30000,"downPayment":3000,"tradeInValue":0,"salesTaxRate":6,"apr":7,"termMonths":60}}'
The response has the header Aztec-Engine-Version: 1 and "engineVersion": "1" in the body. Store the version with the result. You can then explain or reproduce a number later.
Options
Where each surface reports the version:
| Surface | Where |
|---|---|
| REST calculate | The engineVersion body field and the Aztec-Engine-Version header |
| REST schema | The engineVersion body field |
| Embed endpoints | The engineVersion field of the calculator definition and of the calculate response |
| MCP endpoint | engineVersion in result.structuredContent |
After a customer admin opts in, new requests use the new version. The REST API and MCP endpoint pick it up within a minute. The embed endpoints, and the hosted pages that use them, can take up to 5 minutes. Results can differ between versions, so check your integration after you opt in.
Errors and limits
| Status | code | Meaning |
|---|---|---|
| 503 | engine_version_unavailable | The version your cobrand uses isn't loaded. Retry shortly and contact support if it continues. |
The portal only offers released versions that are newer than yours, and it asks you to reload if someone else changed the version first.
Your cobrand's audit history records each opt-in.
Related API reference
The engineVersion field is part of these responses: