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

# API Versioning

> Learn how to specify API versions and stay up to date with changes

## Overview

The Extend API uses versioning to ensure that your integration remains stable as we evolve our API. If you're using the Extend SDK, you don't need to worry about this - the SDK will handle the versioning for you. If you're using the API directly, the version is specified using the `x-extend-api-version` header in your requests.

## Backwards-compatible Changes

We consider the following changes to be backwards-compatible:

* Adding new API resources.
* Adding new optional request parameters to existing API methods.
* Adding new properties to existing API responses.
* Changing the order of properties in existing API responses.
* Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
  * This includes adding or removing fixed prefixes on IDs.
  * Make sure that your integration can handle Extend-generated object IDs, which can contain up to 255 characters.
* Adding new event types.
  * Make sure that your webhook listener gracefully handles unfamiliar event types.

## Specifying a Version

To specify an API version, include the `x-extend-api-version` header in your requests.

The API version is specified in the format `YYYY-MM-DD` and corresponds to the date of the release that introduced the breaking changes.

```bash
curl -X POST https://api.extend.ai/parse \
     -H "x-extend-api-version: 2026-02-09" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "file": { "url": "https://example.com/document.pdf" }
}'
```

*Important*: If you don't specify a version:

* When using an API key made before April 21, 2025, you'll automatically use the legacy version (`2024-12-23`)
* When using an API key made after April 21, 2025, you will receive an error and be required to specify an API version.
* Some organizations may default to a legacy version for backward compatibility predating the introduction of the `x-extend-api-version` header. Reach out to the Extend team if you need to change this.

## Webhook Endpoints

When you create a webhook endpoint in the Extend dashboard, you will be prompted to select the API version you'd like to use. All webhook notifications sent to that endpoint will include the same API version in the `x-extend-api-version` header, ensuring consistency in payload formats.

We strongly recommend keeping the versions defined on your webhook endpoint in sync with the version specified in your requests.

## API Version Changelog

| Version      | Status  | Release Date      | Changes                                                                                                                                                                                                                                                                                                                                                                               |
| ------------ | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `2026-02-09` | Current | February 9, 2026  | New resource-based API with dedicated, fully typed endpoints for extraction, classification, and splitting. Adds synchronous processing endpoints, inline config support (no pre-created resource required), polling helpers, simplified response shapes, and SDK webhook utilities. [See our migration guide for details.](/2026-02-09/api-reference/migrations/2026-02-09/overview) |
| `2025-04-21` | Stable  | April 21, 2025    | Exposed more granular control to several endpoints that use processor configurations. Breaking changes for the processor config schema. Also changes the splitter output shape slightly. [See our migration guide for details.](/api-reference/migrations/2025-04-21)                                                                                                                 |
| `2024-12-23` | Legacy  | December 23, 2024 | Minor, backwards incompatible change: excel files now have their own file type EXCEL and data output shape that is distinct from CSVs. To migrate to new API version, if you are consuming the parsed data from all file types make sure to begin handling EXCEL separately.                                                                                                          |
| `2024-11-14` | Legacy  | November 14, 2024 | Significant, backwards incompatible change: New processor config format which is not fully backwards compatible with `"2024-07-30"`.                                                                                                                                                                                                                                                  |
| `2024-07-30` | Legacy  | July 30, 2024     | Added support for webhook event subscriptions plus a suite of new endpoints for managing processors. And fully deprecated the legacy snake case `workflow_run` keys in favor of camel case.                                                                                                                                                                                           |
| `2024-02-01` | Legacy  | February 1, 2024  | Initial API version with support for workflows.                                                                                                                                                                                                                                                                                                                                       |