# Versioning and deprecation
Source: https://docs.file.ai/api/versioning

> How the fileAI API is versioned today, how breaking changes are caught, and how a deprecation is signalled.

Production

# Versioning and deprecation

Copy pageCopy page

How the fileAI API is versioned today, how breaking changes are caught, and how a deprecation is signalled.

Copy pageCopy page

Every fileAI API endpoint lives under one version, `/v1`. Changes are made additively within it, a CI gate blocks unreviewed breaking changes to the published contract, and an endpoint that is being retired announces it in standard response headers.

## 

[​

](#how-it-works)

How it works

### 

[​

](#one-version-/v1)

One version: `/v1`

All endpoints are under `/v1`, for example `https://api.orion.file.ai/prod/v1/files`. The earlier `/v2` routes (`/v2/extract`, `/v2/split`, `/v2/classify`, `/v2/jobs/{job_id}`, `/v2/forensics`) have been retired and now live under `/v1` with the same request and response shapes. Update the path prefix in any client that still calls `/v2`.

### 

[​

](#what-counts-as-non-breaking)

What counts as non-breaking

fileAI adds to `/v1` without a new version. Write your client to tolerate:

*   new endpoints;
*   new optional request fields and parameters;
*   new fields in responses and in callback payloads;
*   new error `code` values — existing codes are never renamed or repurposed (see [Errors](/api/errors));
*   new values in status and step lists.

Ignore fields you don’t recognize rather than failing on them.

### 

[​

](#how-breaking-changes-are-caught)

How breaking changes are caught

The API contract is a committed OpenAPI document — the same one that generates the API reference tab. Every pull request to the backend runs it through three checks:

Check

What it does

Drift

Fails if code that shapes the API changed but the OpenAPI document wasn’t regenerated.

Lint

Style rules on the OpenAPI document.

Breaking-change diff

Compares the document with the target branch using [oasdiff](https://github.com/oasdiff/oasdiff) and fails on any breaking change.

A breaking change can only ship once it is reviewed and explicitly accepted, with a written reason, in the repository’s list of accepted findings.

### 

[​

](#how-a-deprecation-is-signalled)

How a deprecation is signalled

When an endpoint is deprecated, its responses carry standard headers:

Header

Standard

Example

Meaning

`Deprecation`

RFC 9745

`@1782259200`

When the deprecation was announced, as `@` plus Unix seconds.

`Sunset`

RFC 8594

`Sun, 31 Jan 2027 23:59:59 GMT`

When the endpoint stops working. Only sent once a removal date is set.

`Link`

RFC 8288

`<https://…>; rel="deprecation"`, `<https://…>; rel="successor-version"`

The deprecation notice, and the replacement endpoint when there is one.

The headers are on successful responses, on errors from the endpoint, and on `429`s. They are not on `401` or `403` responses from authentication. The endpoint is also marked `deprecated` in the OpenAPI document. Check for a `Deprecation` header in your client’s logging or monitoring so you hear about a deprecation before its sunset date.

`PATCH /v1/schemas` is marked deprecated in the API reference: to update a file’s extracted values, use `PATCH /v1/files/{fileId}/values` instead. It does not yet send `Deprecation` headers and has no sunset date.

### 

[​

](#deprecated-response-fields)

Deprecated response fields

Error responses still include the legacy `message`, `error` and `statusCode` keys, and responses carry legacy `X-RateLimit-*` headers alongside `RateLimit` and `RateLimit-Policy`. Both are deprecated; move to the replacements described on [Errors](/api/errors).

## 

[​

](#related)

Related

## Errors

Stable error codes and the legacy fields being retired.

## Changelog

What changed, and when.

## Authentication and regions

Base URLs and request conventions.

## Async jobs

The `/v1` home of the former `/v2` operations.

[Previous](/api/idempotency)[

Troubleshooting

Find the cause and fix for common fileAI API failures, from 401s to missing callbacks.

Next

](/api/troubleshooting)

⌘I

## On this page

*   [How it works](#how-it-works)
    *   [One version: /v1](#one-version-%2Fv1)
    *   [What counts as non-breaking](#what-counts-as-non-breaking)
    *   [How breaking changes are caught](#how-breaking-changes-are-caught)
    *   [How a deprecation is signalled](#how-a-deprecation-is-signalled)
    *   [Deprecated response fields](#deprecated-response-fields)
*   [Related](#related)