Microsoft has quietly set a hard deadline for organizations running Azure AI Document Intelligence v2.1 containers: August 31, 2026. The twist? The v2.1 cloud REST API gets a stay of execution until September 15, 2027. That 13-month gap could lull IT teams into a false sense of security if they don’t separate their container deployments from their cloud API calls—and start acting now.
The Dual Deadline: Containers vs. Cloud API
On its lifecycle page, Microsoft points to August 31, 2026, for two products: the former Azure Form Recognizer v2.0 cloud API and the Document Intelligence v2.1 container. The v2.1 REST API, however, will remain supported until September 15, 2027, according to the service’s “What’s new” documentation. This subtle distinction can wreak havoc if an organization treats all “v2.1” assets as having the same shelf life.
A cloud-native application calling the v2.1 API endpoint has more than a year of extra runway compared to an on-premises, edge, or disconnected container running the same generation of AI models. Even more confusing: the v3.0 REST API (version 2022-08-31) will retire on March 30, 2029, giving it a longer tail than v2.1 but shorter than the latest v4.0. This staggered sunset means migration planning must consider not just version numbers but execution environments.
The container retirement is especially pressing for regulated industries, remote field operations, and any scenario where documents cannot touch the public cloud. If you’re running a Kubernetes cluster or Docker host with a v2.1 container for ID Document, Receipt, Invoice, Read, or Layout extraction, August 2026 is your drop-dead date.
Who’s Affected: A Spectrum of Impact
The fallout from this retirement depends on how deeply an organization has woven Document Intelligence into its workflows. Let’s break it down by role:
- IT Administrators and DevOps Engineers: You’ll need to audit every deployment that pulls a container image with “form-recognizer” or “document-intelligence” in its tag. Screens for Docker, Kubernetes, Helm, Terraform, and CI/CD pipelines must be scoured—not just for running containers, but for dormant configuration files and recovery scripts that could reintroduce deprecated images during a rollback.
- Developers: Code that makes REST API calls to a v2.1 endpoint might seem safe until 2027, but any abstraction layer that also routes to a container will hit the earlier wall. Inspect source code, SDK versions, and API gateways. The v4.0 SDKs (defaulting to the 2024-11-30 API) are the recommended path forward, but not all models are available in v4.0 containers yet.
- Business Decision Makers: Compliance and procurement policies may need updating. You might approve v4.0 as the standard for cloud APIs while carving out exceptions for v3.1 containers where newer images lack required document models. This isn’t a one-size-fits-all upgrade—it’s a model-by-model decision.
The Version Landscape: From Form Recognizer to v4.0
To understand the current predicament, a quick history helps. The service we now call Azure AI Document Intelligence started life as Form Recognizer. Its v2.0 API, introduced in 2020, provided basic OCR and form recognition. The v2.1 release added prebuilt models for receipts, invoices, business cards, and ID documents, along with a container option for disconnected scenarios.
In 2022, Microsoft rebranded the service and launched the v3.0 API with significant architectural improvements and new models. Then came v3.1, and in late 2024, the v4.0 REST API reached general availability, bringing better accuracy, searchable PDFs in the Read model, and updated SDKs. Throughout this evolution, container availability has lagged behind cloud API features. As of now, the container lineup looks like this:
| Container Version | Supported Models | Support End Date |
|---|---|---|
| v2.1 | Read, Layout, ID Document, Receipt, Invoice | August 31, 2026 |
| v3.0 | Read, Layout, General Document, Business Card, Custom, ID Document, Receipt, Invoice (broader set) | March 30, 2029 |
| v3.1 | Read, Layout, ID Document, Receipt, Invoice | To be announced |
| v4.0 | Read, Layout | Current (no end date yet) |
Thus, simply moving all workloads to the “latest” container version isn’t feasible if you rely on models that v4.0 doesn’t yet containerize. Microsoft’s own migration guidance recommends v4.0 for new cloud development, but for containers, the decision must be model-driven.
Your Migration Playbook: Practical Steps
The good news: you have time—but only if you start methodically now. Here’s a condensed action plan drawn from best practices and Microsoft’s documentation.
1. Inventory Everything That Touches Document Intelligence
Don’t assume a simple repository search will catch all dependencies. Use command-line tools (PowerShell’s Select-String, git grep, kubectl, docker) to hunt for strings like “formrecognizer”, “documentintelligence”, “/v2.0/”, “/v2.1/”, and “api-version” across source code, deployment manifests, operational scripts, and container registries. Tag each asset with its execution environment (cloud API call vs. container), model type, and owner.
2. Classify and Map the Models
For each container workload, check which model it uses: Read, Layout, ID Document, Receipt, Invoice, Business Card, General Document, or Custom. Then consult the container matrix above to find a supported replacement path.
- Read or Layout? Target v4.0 containers directly, as they’re available and bring improvements like searchable PDFs.
- ID Document, Receipt, or Invoice? Move to v3.1 containers, which are the newest that support these models.
- Business Card, General Document, or Custom? You’ll likely need v3.0 containers for now, but monitor for v4.0 expansion. Note that v3.0 will retire in 2029, giving a longer runway—but don’t wait until then.
3. Don’t Just Swap Images—Test Contracts Rigorously
A version bump can break your document processing pipeline even if the HTTP status code is 200. The structure of JSON responses, field names, confidence scores, polling patterns, and error handling can shift between versions. Create a set of “golden documents” (representative invoices, receipts, IDs) and compare outputs from the old and new containers side by side. Test malformed files, timeouts, and restarts. Ensure your applications can parse the new response format before cutting over.
4. Decouple Client Changes from Container Changes
If possible, first update your application to accept both old and new endpoints and response structures. Then route a portion of traffic to the new container. This lets you validate in production with a quick rollback path—but remember, after August 2026, rolling back to v2.1 means running unsupported software.
5. Update All Support Artifacts
Documentation, dashboards, health checks, disaster recovery runbooks, and CI/CD pipelines must all be revised to remove references to v2.1. A rolled-back deployment during a post-retirement incident would be disastrous. Purge old image tags and manifests from source control and recovery scripts.
6. Don’t Overlook Cloud API Calls
If your applications use the v2.1 REST API, you have until September 2027, but early migration is wise. The v4.0 API is the natural target, but cross-check your models: v4.0’s API supports more models than its containers, so you might be able to move earlier. Use Azure Advisor retirement recommendations as a starting point, but verify manually—Advisor’s coverage may not be complete.
The Road Ahead: Watching v4.0 Container Expansion
Microsoft is actively expanding v4.0 capabilities. The recent additions of Read and Layout containers are promising, and the v4.0 API already supports many more models in the cloud. We expect container catalogs to grow, but no roadmap has been publicly committed. Organizations with complex document workflows should keep a close eye on the “What’s new in Document Intelligence” page and plan for a future where v4.0 is the universal container platform—just don’t bet on it arriving before your deadline.
In the meantime, treat this retirement as a forcing function to modernize document processing pipelines, improve testing hygiene, and get a true picture of your AI dependencies. The clock is ticking, but a clear-headed inventory today can turn a compliance scramble into a routine upgrade.