Skip to main content

Upgrades

Migrating to Unomi 4

Familiar REST map, additive APIs, and an optional REST compatibility bridge for Unomi 2.x and 3.x clients.

The API stays familiar

Unomi 4 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 4.0 — new capabilities (tenants, tasks, …) are additive.

Native Unomi 4.0 authentication expects tenant API keys. For a calm cutover, enable REST compatibility mode (single-tenant) so Unomi 2.x and 3.x clients keep working while you migrate traffic, then disable the mode when ready.

API stability and REST compatibility for Unomi 2.x and 3.x clients

Migration paths

  1. Upgrade to 4.0 — Java 17+ minimum, QueryBuilder ID renames, ES7→ES9 data migration, tenant API keys, and new APIs. A 3.0.x install already has the runtime steps and still needs the tenant keys and new APIs.
  2. REST compatibility mode — phased transition for Unomi 2.x and 3.x clients
  3. Optional Elasticsearch → OpenSearch migration

Follow the official manual chapters rather than duplicating long procedures here:

Open the manual Unomi 4 intro

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

← All posts