Migration guides

Use this page when an Euler API or SDK version changes. The current public API is v1, so this guide documents the v1 compatibility baseline and the required path for a future v1-to-v2 migration without claiming that v2 exists today.

Current v1 baseline

Before upgrading a customer integration, pin the contract and SDK versions you are using:

curl -fsS https://api.euler.sudotank.com/healthz
uv run python tools/sdk/generate.py --check
cd sdks/typescript && npm ci && npm run build
python -m compileall -q sdks/python/src

Use openapi/euler.openapi.json to compare hosted routes and generated SDK methods. For v1, customer code should treat hosted /v1 routes as stable and local package primitives as separately versioned integration helpers.

Future v1-to-v2 migration checklist

When Euler ships a future v2 contract, use this order:

1. Read the dated changelog entry and confirm the OpenAPI info.version.
2. Regenerate TypeScript and Python SDKs from openapi/euler.openapi.json.
3. Replace deprecated route paths or request fields in a branch.
4. Run uv run python tools/sdk/generate.py --check.
5. Run cd sdks/typescript && npm ci && npm run build.
6. Run python -m compileall -q sdks/python/src.
7. Re-run the public quickstart against the hosted API base.
8. Re-run MCP or local package flows that depend on search, saved slices, chunk bridge plans, transform recipes, or feedback import.

Breaking-change policy

The following changes require a migration note before release:

• removing or renaming a hosted /v1 route;
• making an optional request field required;
• removing response fields used by generated SDKs;
• changing authentication, CORS, or approval checkpoint semantics;
• changing SDK package names or publish behavior;
• promoting a local package primitive to a hosted REST endpoint.

Rollback

If a migration fails, keep the previous SDK version pinned, continue using the existing /v1 routes, and verify readiness receipts or export receipts before trusting newly generated artifacts. Euler does not require a paid API or hosted LLM to complete API/SDK migrations.