Soft change. The wire contract is unchanged — request and response shapes have always been the same. What changed is how much of that contract the spec at /api/v1/openapi makes machine-readable.
If your client never re-generates from the spec, you don't need to do anything. If you do re-generate (manually or in CI), expect typed request bodies on more operations. Your code may need .body property casts or named imports updated to match the new generated type names.
Two version numbers, separate cadences
HelpMesh tracks two versions independently:
•OpenAPI info.version (e.g. 1.12.0) tracks the API contract — bumps when endpoints, request bodies, or response shapes change. Every bump is documented either in a migration guide (here) or the changelog.
•Product version (e.g. 5.3.0-alpha.6) tracks the whole platform — UI ships, infra changes, internal refactors — and bumps far more often.
Pin to the URL path — /api/v1 — that's the only breaking-change boundary. A v2 would only ship if a backwards-incompatible change were unavoidable.
Spec evolution
spec 1.13.0
shipped with v5.3.0-alpha.8
Response schemas added to 17 GET list endpoints (paginated and non-paginated alike) plus 7 AI mutation endpoints + uploads/presigned + threads/batch. Generated SDKs in other languages stop typing list responses as `any[]` and AI op return values as `unknown`. 16 new named response shapes (Inbox, Team, Label, User, CannedResponse, CustomField, SlaPolicy, KbArticle, KbCollection, WebhookDelivery, AuditLog, SystemHealth + AI response shapes).
Affects: Anyone re-generating SDKs from the spec. Response types are now first-class — TypeScript users will see narrowed types on `.then()` callbacks; Python/Go users will get typed dataclasses/structs back.
spec 1.12.0
shipped with v5.3.0-alpha.6
25 endpoints upgraded from summary-only to rich requestBody. Thread sub-resources (assign, snooze, labels, merge, batch), scheduled-meetings lifecycle (PATCH/DELETE/attendance/recording), the entire AI namespace, catalog mutators (POST inboxes/teams/labels/users/canned-responses/custom-fields/sla-policies), KB POST endpoints, privacy POST endpoints, auth lifecycle (forgot/reset/change), tenant settings, and uploads. 11 reusable enums named.
Affects: Anyone re-generating SDKs with openapi-generator-cli, OpenAPI Codegen, oapi-codegen, etc. Typed request bodies replace `body?: any` on the affected operations.
spec 1.11.0
shipped with v5.1.1
First wave of rich requestBody schemas. 9 endpoints schematized: POST /threads, POST /threads/{id}/messages, POST /threads/{id}/reply, POST /webhooks, POST /threads/{id}/schedule-meeting, POST /webhooks/{id}/test, plus three early ai-related ops. Spec `info.description` gained the host callout (helpmesh.io vs app.helpmesh.io) and the OpenAPI-version-vs-product-version explainer.
Affects: Same audience as 1.12 — re-generated clients pick up typed bodies on these specific operations. Behaviour at the wire is unchanged.
spec 1.10.0 and earlier
shipped with v5.1.0 and earlier
Spec was hand-written; most operations had only a `summary`. Generated SDKs produced clients with `body?: any` for the bulk of the mutating API surface. Path indexing worked; type generation did not.
Affects: Customers maintaining hand-written wrappers (the recommended path before 1.11). The runtime contract was the same — requests with the right Zod-validated shape always worked.
Re-generating clients
The spec is published at https://helpmesh.io/api/v1/openapi as OpenAPI 3.1. Common regeneration commands:
Spec version bumps that just enrich existing operations (adding schemas to summary-only routes, clarifying descriptions) don't break anyone. The bump is a signal to regenerate, not a forced break. We bump /api/v1 → /api/v2 only when a backwards-incompatible wire change is unavoidable.
