> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/build/api-changes/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Understand API changes

> Understand how Middesk manages API versioning and backwards compatibility.

Middesk uses major-release versioning for its API, currently in version 1 (`v1`). This guide explains how Middesk categorizes API changes and manages backwards compatibility.

## Breaking changes

Breaking changes are **not** backwards compatible and can cause existing integrations to fail. Middesk rarely makes breaking changes, but when necessary, notifies affected customers in advance and provides an opt-out option.

**Examples of breaking changes:**

* Removing or renaming fields in API responses
* Changing the data type of existing fields
* Removing or deprecating API endpoints
* Modifying authentication methods or security protocols
* Decreasing rate limits
* Removing webhook events

## Non-breaking changes

Non-breaking changes are backwards compatible with existing integrations. These are typically additive changes that don't affect current functionality.

**Examples of non-breaking changes:**

* Adding new API endpoints
* Adding optional request parameters
* Adding new fields to API responses
* Changing the order of fields in responses
* Changing opaque string formats (such as IDs or error messages)
* Adding new webhook events

Non-breaking changes can be further broken down into disruptive and non-disruptive changes.

### Disruptive changes

Some backwards-compatible changes may still affect your business logic or workflows. For disruptive changes, Middesk contacts affected customers in advance and uses feature flags to opt those users in.

**Examples of disruptive, non-breaking changes:**

* Adding secondary data sources for address verification (such as Google Places or websites)
* Auto-subscribing customers to new webhook event types
* Changing data sources for the watchlist database
* Adding new status values (`success`, `warning`, `failure`) to existing insights or tasks

### Non-disruptive changes

Most API changes fall into this category and don't affect your integration.

**Examples of non-disruptive, non-breaking changes:**

* New endpoints like Policies
* New Task types
* New fields in the Businesses API
* Additional optional filters for `GET /v1/businesses`

> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.

> Understand how Middesk manages API versioning and backwards compatibility.