VersioningComing soon

The Matchai API is versioned so that an integration you build keeps working. This page explains what stays the same, what can change under you, and how you hear about changes that need your attention.

The version is in the pathCopy link to this section

The major version is part of every address:

https://api.matchai.co/v1

Webhook events carry the same version in their body, as "api_version": "v1". An address that starts with /v1 behaves the way this documentation says for as long as /v1 exists.

Changes that do not need a new versionCopy link to this section

Matchai can ship these at any time, without a new version and without a notice beyond the changelog:

• New endpoints, new webhook event types and new scopes. A connection never gains a scope it was not granted.
• New optional request fields and new query parameters.
• New fields in responses and in webhook payloads.
• New values in an enum, such as a new status, a new profession or a new event type.
• New error codes and new error types.
• A different order of fields in a JSON object.
• Changes to the length or format of ids and cursors. Ids are opaque.
• Fixes to behaviour that did not match this documentation.

So write your client to expect them:

• Ignore fields you do not know.
• Treat an unknown enum value as "other". Do not crash on it, and do not guess its meaning.
• Never parse or build ids. Store them and send them back.
• Branch on an error's code, and fall back to its type and status when you meet a code you do not know. See errors.
• Ignore webhook events you do not handle. Answer 2xx and move on.

Breaking changesCopy link to this section

A breaking change is one that can make a correct integration stop working. These always ship as a new major version, next to the old one:

• Removing or renaming an endpoint, a field, a query parameter, an enum value, an event type or a scope.
• Changing the type, format or meaning of an existing field.
• Making an optional request field required, or adding a new required one.
• Refusing requests that used to be accepted, by tightening validation.
• Changing the HTTP status or the code that an existing situation produces.
• Changing how authentication works, or narrowing what a scope allows.

A new major version, such as /v2, runs next to /v1. It never replaces /v1 in place, and nothing is moved to it for you.

DeprecationCopy link to this section

Matchai does not remove a version, an endpoint or a field without telling you first. A deprecation is announced in the changelog ahead of time, and each announcement says:

• what is being retired, and what replaces it;
• how to move across;
• what, if anything, you need to do.

The announcement comes well before the old behaviour is removed, so that you have time to move. Read the changelog when you plan a release, and when you hear nothing for a while.

The MCP server is versioned separatelyCopy link to this section

The MCP server reports its own version in serverInfo.version, a semantic version that changes when a tool or a field is added or changes shape. Tools are described to the assistant each time it connects, so a well-behaved client picks up new tools without any change on your side.