Versioning

The version is part of the URL: /v1. Within a version, responses change only in backward-compatible ways. Breaking changes ship in a new version at a separate URL.

#Version numbers

• The API version is in the path: https://api.melioralab.io/v1. GET /v1/me also returns it in the api_version field.
• The event format version is in the api_version field of every event. It is currently 2026-10-18. It changes when the set of event fields changes. The value matches the format version of the same events in the organization's webhooks.

#Backward-compatible changes

These changes can appear in v1 without a new version:

• new routes;
• new optional request parameters;
• new fields in responses and nested objects;
• new event types in the feed;
• new error codes under existing HTTP statuses;
• changes to the detail text of errors.

#Breaking changes

We don't make these changes in v1: removing or renaming fields, changing a field's type, requiring a new parameter, or changing the meaning of existing values. If one of these becomes necessary, we'll release a new version at a separate URL. We'll announce it and the migration timeline in advance in the changelog.

#Building a resilient client

• Ignore unknown fields in responses. Don't fail on them.
• Treat an unknown enum value as unknown. We try not to extend v1 enums, but this code costs you nothing.
• Skip events of unknown types, but still save the cursor of the page they came on.
• Handle an unknown error code by its HTTP status.
• Don't parse the format of IDs or cursors: the message id and next_cursor are opaque.

#Changelog

Every API change is recorded in the changelog. The openapi.json specification is updated along with it.