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

​
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

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);
  • new values in status and step lists.
Ignore fields you don’t recognize rather than failing on them.

​
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: 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

When an endpoint is deprecated, its responses carry standard headers: The headers are on successful responses, on errors from the endpoint, and on 429s. 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

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.

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.