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

We aim to limit any breaking changes. Where necessary, major changes may be rolled out over versioned endpoints and upgrading would be required to support new features.

Truly breaking changes, that would require changes to your code, are considered a last resort.
They will be communicated in advance and we'll coordinate and support your updates.

A change is breaking when an existing integration stops working while still sending the same requests.

> **Note**
>
> Some changes we treat as non-breaking can still be breaking changes to generated API types. We'll roll out major versions of our SDKs where possible. Existing integrations keep working at runtime.

## Request Shape

### Breaking

* Adding a new, required, field
* Modifying the data type of an existing field
* Removing support for enum values that were previously accepted

### Non-breaking

* Adding a new, optional field
* Removing a field that was previously optional
* Making a required field optional or nullable. Existing requests keep working. You only get the new behavior by changing what you send.

## Response Shape

### Breaking

* Removing a field
* Changing the data type of an existing field
* Making a field nullable, when an existing response can return `null` without a change to the request

### Non-breaking

* Adding a new field
* Making a field nullable, while clients that still send the original request keep the original response contract

#### Introducing optional

Patient create `email`:

```ts
// existing contract
request: { email: string }
response: { email: string }

// introducing optional
request: { email?: string | null }
response: { email: string | null }
```

The existing contract still holds. Clients that still send `email: string` receive `email: string` on every response.

## Enums / Union Types

Enums and union types determine acceptable values for a single field.
The breaking/non-breaking definitions here are generally true.

The only thing we consider a breaking change, is the removal of an enum value or union type that was previously accepted, inside a request.

Additional enum values or types, in either request or response, are considered non-breaking.

We expect client integrations to be able to handle "unknown" enum values and types gracefully.

## Behavior Changes

> **Warning**
>
> Breaking behavior changes, tied to API changes, are breaking API changes

In addition to the conventions here, generalized breaking changes to concepts and behavior may render an API change as breaking.

For example, the addition of a `status` value in a `Service` lifecycle would be considered critical enough to be breaking.

However, the additional of a triage `TaskType` would *not* be considered breaking - it should be treated as unknown.