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

# Versioning & breaking changes

> How the API and SDKs are versioned, and what we do when something has to break.

## The API

The public API is versioned in the path: `https://api.engini.io/v1`. Everything documented here lives under `/v1`.

**Additive changes ship without notice** and your integration must tolerate them:

* New endpoints and new optional request fields
* **New fields in responses** - deserialize permissively; don't fail on unknown keys
* New `errorCode` values - treat an unrecognized code as a generic failure of its HTTP status
* New enum members
* New entries in the application and tool catalog

**Breaking changes** - removing or renaming an endpoint, removing a response field, tightening validation, or changing a type - are announced in the [changelog](/changelog) before they take effect.

## The SDKs

`engini-client` (the generated REST client) and `engini` / `@engini/sdk` (the ergonomic layer) follow semantic versioning, currently in the `0.x` range - so a **minor** bump can carry a breaking change, and a patch never does.

The generated client is regenerated from the OpenAPI spec on every API release, and its version bump is computed from a machine diff of the spec rather than chosen by hand. If the diff says breaking, the version says breaking.

<Warning>
  Pin a range, not a floating latest, and read the changelog before widening it:

  ```
  engini>=0.11,<0.12          # Python
  "@engini/sdk": "^0.12.0"    # TypeScript
  ```
</Warning>

## How we handle a breaking change

When something on a surface with real users has to break or be renamed, the default pattern is:

1. Add the new path and keep the old one working
2. Announce the deprecation in the changelog with a date
3. Ship SDKs that use the new path
4. Remove the old path only after that window

We're stating this up front because you're entitled to know how we'll treat your integration before you build on it.

## Deprecation signals

* The [changelog](/changelog) is the authoritative record - check it before upgrading
* Deprecated tools carry `isDeprecated: true` in the catalog; `GET /v1/tools` excludes them unless you pass `includeDeprecated=true`
* Deprecated endpoints keep working through their announced window

## Staying current

```bash theme={null}
pip install -U engini engini-client
npm install @engini/sdk@latest @engini/client@latest
npm install -g @engini/cli@latest
```

Verify what you're actually running - useful in a bug report:

```bash theme={null}
engini --version
python -c "import engini, engini_client; print(engini.__version__, engini_client.__version__)"
```