Skip to main content
HelpMesh

Documentation

Migration Guides

Upgrade with confidence. Each guide covers what changed, why, who's affected, and the exact upgrade steps with before/after examples.

DocsMigrations

When you need a migration guide

Most HelpMesh releases are additive — new endpoints, new fields, new webhook events. Those land quietly via continuous deployment and the changelog is all you need. Migration guides exist for the rare changes where code that worked before this version may not work after. Each guide names exactly who is affected and what to change.

Available guides

Breakingv5.3.0-alpha.4

Error codes: numeric → semantic

Every public-facing error code switched from opaque numerics (HM-AUTH-001) to SCREAMING_SNAKE_CASE semantics (HM-AUTH-MISSING). Status codes preserved; codes split where one numeric meant several conditions.

Affects: Any code that pins on err.code string values — typically SDK consumers, alerting rules, dashboards.

Soft changespec 1.10 → 1.13

OpenAPI spec: requestBody + response schemas shipped

The /api/v1/openapi spec gained rich requestBody schemas (9 → 45 ops) AND response schemas on every GET list endpoint + AI op across the v5.1.1 → v5.3.0-alpha.8 window. Re-generated SDKs get typed bodies AND typed responses for the bulk of the API surface.

Affects: Anyone re-generating clients with openapi-generator-cli or similar tools.

How HelpMesh handles breaking changes

  • •URL versioning is the only contract boundary. Every endpoint lives under /api/v1/.... A v2 would only ship if a backwards-incompatible change were unavoidable.
  • •OpenAPI info.version tracks the contract. Bumps minor when shapes change, never silently. The product version (5.3.0-alpha.6) is independent and bumps far more often.
  • •Compatibility shims when possible. Where useful, deprecated values get a translation map (e.g. the LEGACY_CODE_ALIASESreverse-lookup that ships with the error-code migration). Responses themselves emit the new shape — the shim is for downstream consumers translating in their own code.
  • •SDKs absorb most diff. The official @helpmesh-io/sdk tracks the API contract — a fresh npm i @helpmesh-io/sdk picks up the latest shapes without code changes for additive releases.

Stuck on a migration?

Email support@helpmesh.io with the version you're upgrading from and to, plus an X-Request-Id from a failing call if applicable.