Skip to main content

Upgrades

Migrating from Unomi 2.x to Unomi 3

Familiar REST map, additive APIs, and an optional V2 compatibility bridge.

The API stays familiar

Unomi 3 does not rip out the 2.x REST map. In the OpenAPI specs tracked for testing, every one of the 119 Unomi 2.x paths is still present in 3.1 — new capabilities (tenants, tasks, …) are additive.

Native Unomi 3.1 authentication expects tenant API keys. For a calm cutover, enable V2 compatibility mode so existing clients keep working while you migrate traffic, then disable the mode when ready.

API stability and V2 compatibility

Migration paths

  1. 2.x → 3.0 — Java 17+ minimum, QueryBuilder ID renames, ES7→ES9 data migration
  2. 3.0 → 3.1 — tenant auth model, new APIs
  3. V2 compatibility mode — phased client transition
  4. Optional Elasticsearch → OpenSearch migration

Follow the official manual chapters (including V2 compatibility) rather than duplicating long procedures here:

Open the manual Unomi 3 intro

Path stability does not mean authentication never changes. Prefer tenant API keys in 3.1; use compatibility mode as the bridge.

← All posts