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

# Versioning and deprecation — how the 2Fin API changes

> Which parts of the 2Fin API carry a version, how payload versions are labelled, how retired endpoints answer, and the deprecation policy.

## What is versioned today

| Surface | Version | How it shows |
| - | - | - |
| Integration API | `v1` | In the path: `https://api.ai2fin.com/api/integrations/v1/...` |
| Webhook payloads | `2026-07-01` | `apiVersion` in every event envelope, and in `GET /api/integrations/v1/me` |
| MCP | MCP protocol `2025-11-25` | Negotiated by the client at `initialize`; advertised in the server metadata |
| REST API (`/api/...`) | Not versioned | Changes are made so existing callers keep working (below) |

The REST API is the first-party surface the 2Fin apps use. It is documented so you can script against your own account, and it changes more often than the Integration API. If you are building something for other people to use, build on the Integration API, webhooks or MCP.

## Changes that do not need a new version

These can happen at any time and are listed in the [changelog](https://docs.ai2fin.com/api-reference/changelog.md):

* new endpoints, new optional request fields and new query parameters;
* new fields in a response or an event's `data`;
* new values in a field that already has several (for example a new `source` on a webhook, or a new data-history `kind`);
* new error messages for the same status code.

Write clients that ignore fields they do not know and handle values they have not seen.

## Breaking changes

A change that would break a working client (removing or renaming a field, changing its type or meaning, making an optional field required, removing an endpoint) is not made in place on a versioned surface. It comes as a new Integration API version alongside `v1`, or a new `apiVersion` for webhook payloads.

## How endpoints are retired

1. The operation is marked `deprecated: true` in the [OpenAPI document](https://docs.ai2fin.com/api-reference/openapi.json) and the change is announced in the changelog, with the replacement where there is one.
2. When it is removed, the route keeps answering `410 Gone` with a message that names the replacement, rather than disappearing into a `404`.

Endpoints that answer this way today:

| Retired | Use instead |
| - | - |
| `POST /api/auth/login` | `POST /api/enterprise-auth/login` (the `410` body includes `redirectTo` and `migration`) |
| `POST /api/auth/register`, `POST /api/oidc/register` | `POST /api/enterprise-auth/register` |
| `POST /api/chat/message` | `POST /api/chat/stream` (the `410` body includes `migrateTo`) |
| `DELETE /api/intelligent-categorization/cache` | Nothing: the cache it cleared no longer exists |

The OAuth endpoints moved from `/api/chatgpt/oauth/...` to `/api/oauth/...`. The old paths still work, with their own discovery document, for clients that saved them; new clients should use the paths in `/.well-known/oauth-authorization-server`.

## Staying informed

* The [API changelog](https://docs.ai2fin.com/api-reference/changelog.md) lists changes that affect API callers, newest first.
* Watch for `deprecated: true` in the OpenAPI document, which is the source of the API reference pages.
* Questions about a change: [support@ai2fin.com](mailto:support@ai2fin.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.