> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedatacity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> How the Company Matching API is versioned, what counts as a breaking change, and where to find out what changed.

The API carries two version numbers. They answer different questions.

|                                   | What it tells you                              | Where you see it                                                  |
| --------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- |
| **API version** (`/api/v1`)       | The wire contract: paths, fields, status codes | The URL prefix on every endpoint                                  |
| **Release** (for example `1.0.1`) | The software build serving that contract       | `info.version` in the OpenAPI spec, and the Swagger UI at `/docs` |

## API version

Every endpoint lives under `/api/v1`. The prefix changes only for a breaking change to the wire contract, which would move to a new prefix such as `/api/v2`.

<Note>
  While the API is in beta, treat the contract as settling rather than frozen. Release 1.0.0 renamed two fields under `/api/v1` without a prefix change — see the [changelog](/company-matching/changelog). Breaking changes are always listed there.
</Note>

## Release

The release follows [semantic versioning](https://semver.org/) and is published as `info.version` in the OpenAPI spec:

```text theme={null}
https://datamatcher-api.thedatacity.com/api/v1/openapi.json
```

* **Patch** (`1.0.0` → `1.0.1`): fixes and operational changes. No change to the contract.
* **Minor** (`1.0.x` → `1.1.0`): backwards-compatible additions, such as a new optional field.
* **Major** (`1.x` → `2.0.0`): a breaking change to the contract.

A release can ship with no visible change to the API. The changelog says so when that happens.

## What counts as a breaking change

Breaking:

* Removing or renaming an endpoint, request field, or response field.
* Changing the type of an existing response field.
* Tightening validation on a field that previously accepted broader input.
* Changing the JSON error envelope.

Not breaking:

* New endpoints.
* New optional response fields.
* New optional request fields.
* Fixes that bring actual behaviour in line with documented behaviour.

Write your client so that unknown response fields are ignored. That is what makes non-breaking additions safe.

## Discovering changes

* Read the [changelog](/company-matching/changelog) for material changes and the release each shipped in.
* Diff the OpenAPI spec between deploys for a precise record of contract changes.
* Email [support@thedatacity.com](mailto:support@thedatacity.com) with questions about a specific change.

<Snippet file="need-help.mdx" />