Azure AI Document Intelligence v2.1 Containers End August 31, 2026

Microsoft will end support for the Azure AI Document Intelligence v2.0 cloud API and the Document Intelligence v2.1 container on August 31, 2026, but that date does not retire every v2.x workload. Administrators should inventory cloud calls and container deployments separately, then move containerized Read and Layout workloads to v4.0 while using v3.1 as the practical landing zone for ID Document, Receipt, and Invoice deployments that v4.0 containers do not yet support.
Microsoft’s lifecycle documentation identifies two products at the August deadline: the former Azure Form Recognizer v2.0 API and the v2.1 container. The Document Intelligence v2.1 REST API remains supported until September 15, 2027, according to Microsoft’s current product documentation.
That distinction changes both the urgency and the migration plan. A cloud application calling the v2.1 REST API has more time than a Kubernetes cluster, Docker host, or disconnected deployment running a v2.1 container—even if both are casually described inside the organization as “Form Recognizer v2.”

Split the Inventory Before Choosing a Target​

The first job is not upgrading an SDK. It is establishing whether each dependency is a cloud API call, a container invocation, or an application abstraction hiding one of those underneath.
Repository searches should cover source code, configuration files, deployment templates, build pipelines, and operational scripts. On a Windows administration workstation, PowerShell can provide an initial sweep:

Get-ChildItem -Path . -Recurse -File |
    Select-String -Pattern `
        "formrecognizer",
        "documentintelligence",
        "/v2.0/",
        "/v2.1/",
        "api-version",
        "azure-cognitive-services/form-recognizer"

Organizations using Git repositories can run a broader search with git grep:
git grep -n -i -E "formrecognizer|documentintelligence|/v2\.(0|1)/|api-version|azure-cognitive-services/form-recognizer"
The results should be classified rather than immediately replaced. Record the calling application, endpoint type, model, API or container version, authentication method, owner, deployment environment, and whether the workload can be tested without production documents.
Container discovery needs its own pass because an application may call an internal service name without revealing the underlying image version. Docker administrators can begin with:

docker ps -a --format "{{.Names}} {{.Image}}"
docker image ls --format "{{.Repository}}:{{.Tag}}"

For Kubernetes, inspect live workloads as well as the manifests stored in source control:

kubectl get deployments,statefulsets,daemonsets -A -o yaml
kubectl get pods -A -o jsonpath="{range .items
- }{.metadata.namespace}{'\t'}{.metadata.name}{'\t'}{range .spec.containers
- }{.image}{'\n'}{end}{end}"

Search Helm values, Kustomize overlays, YAML manifests, Terraform, Bicep, Azure DevOps pipelines, and GitHub Actions for the same Form Recognizer and container-image strings. A cluster inspection alone can miss a retired image tag that will return during the next rollback, disaster-recovery deployment, or environment rebuild.
The final inventory should therefore include dormant artifacts. An unused deployment template is still a migration risk if it remains the documented recovery path.

---

V4.0 Is the Default, Not the Universal Container Replacement​

Microsoft recommends the v4.0 API version 2024-11-30 for new development, and the current SDK generation defaults to that version. That makes v4.0 the sensible starting point for cloud modernization and for container workloads whose model is already available.
Container support is narrower than cloud API support, however. Microsoft’s current matrix lists:

• V4.0 containers for Read and Layout.
• V3.1 containers for Read, Layout, ID Document, Receipt, and Invoice.
• V3.0 containers for the broader set that includes Read, Layout, General Document, Business Card, and Custom models.

That matrix—not the newest version number—should determine the replacement path.
A v2.1 Read or Layout container is a direct candidate for v4.0 evaluation. Administrators still need compatibility testing, but there is no model-availability reason to stop at v3.1.
A v2.1 ID Document, Receipt, or Invoice container cannot simply be reassigned to a v4.0 container because those models are not in the current v4.0 container set. For these workloads, v3.1 is the available newer container generation listed by Microsoft.
Business Card, General Document, and Custom container deployments require additional care. The documented v3.0 container generation has the broader model coverage, while the newer v3.1 and v4.0 container sets do not provide every one of those models. Administrators should not interpret the August deadline as evidence that every workload has a feature-equivalent v4.0 image.
This creates a two-track policy:

1. Move eligible Read and Layout containers toward v4.0.
2. Place workloads requiring ID Document, Receipt, or Invoice on v3.1 while monitoring Microsoft’s v4.0 container expansion.
3. Treat Business Card, General Document, and Custom deployments as model-specific architecture decisions rather than routine version bumps.

The difference also matters for procurement and governance reviews. A team may approve v4.0 as its standard Document Intelligence API while retaining v3.1 containers for a defined exception, because cloud API capabilities and container capabilities are not identical.

Find the Contract Changes, Not Just the Version String​

Changing an image tag or installing the current SDK proves little by itself. Document-processing integrations often embed assumptions about operation paths, model identifiers, asynchronous polling, JSON structure, confidence values, field locations, and authentication configuration.
Build the migration around captured contracts. For each workload, retain sanitized examples of the request, response, expected extracted fields, and application-visible output before changing versions.
The test plan should cover at least these areas:

• Confirm that the new request path, API version, HTTP method, headers, content type, and request body match the selected API or container generation.
• Verify every model name rather than assuming an old prebuilt or custom-model identifier remains interchangeable.
• Test the initial analysis request and the result-polling operation, including how the application obtains and stores the operation location or result identifier.
• Compare response nesting, page information, tables, selection marks, key-value pairs, documents, fields, confidence values, and error objects against the application’s parser.
• Revalidate API-key handling and container billing configuration without copying secrets into manifests or test logs.
• Run representative documents through both versions and compare business outputs, not merely successful HTTP status codes.
• Exercise malformed files, unsupported formats, empty documents, timeouts, retries, and partial downstream failures.
• Test container restarts, node replacement, image pulls, health probes, scaling, and rollback procedures.
• Rebuild the deployment from source-controlled manifests to prove that recovery automation no longer restores v2.1.

Golden-document testing is especially important. A technically successful response can still break an invoice workflow if a field moves, a parser expects an older response node, or downstream validation treats a changed or missing value as authoritative.
Authentication deserves separate testing because cloud and container deployments have different operational boundaries. Cloud applications may obtain credentials from application configuration or a managed secret store, while containers require their runtime billing and key settings to be valid. A migration that succeeds on a developer laptop can fail in production when secret names, environment variables, network access, or deployment policies differ.

The September 2027 Date Is Not an Extension for Containers​

The most dangerous planning error is attaching the Document Intelligence v2.1 REST API date to a v2.1 container. Microsoft lists September 15, 2027 for the v2.1 cloud REST API, but the v2.1 container is named separately on the lifecycle page with support ending August 31, 2026.
An internal asset labeled “v2.1” is therefore not classified well enough. The inventory must say v2.1 REST API or v2.1 container, along with the model being used.
The same discipline applies to the v2.0 cloud API. Teams should inspect code for explicit legacy paths, but also examine SDK packages and internal wrappers that construct requests dynamically. API gateways, reverse proxies, workflow products, desktop utilities, scheduled PowerShell tasks, and integration services may conceal calls that do not appear in the primary application repository.
Azure Advisor retirement recommendations can supplement this work, but they should not be treated as a complete software bill of materials. Microsoft’s Advisor documentation currently identifies the v2.0 API retirement while indicating that impacted-resource availability is still to be updated. Direct inspection of applications and deployments remains necessary.

---

Make the Cutover Reversible​

The remaining time before August 31 should be used to remove uncertainty, not to schedule a single in-place production upgrade. Stand up the selected v3.1 or v4.0 target beside the legacy deployment, replay representative documents, and compare outputs before changing callers.
Where possible, separate client changes from container changes. First make the application capable of selecting an endpoint and handling the new contract; then redirect a controlled share of traffic. Keep rollback bounded and temporary, because restoring a v2.1 container after August 31 would not restore Microsoft support.
Operational documentation must change with the deployment. Update image references, API-version settings, model mappings, secret names, health checks, dashboards, alerts, recovery procedures, and support runbooks. Remove obsolete v2.1 manifests and cached assumptions once rollback is closed so that the retired generation cannot quietly return.
The August 31, 2026 retirement is ultimately two deadlines sharing one date, not a blanket shutdown of Document Intelligence v2.1. Administrators who identify the execution model and document model separately can move Read and Layout directly toward v4.0, use v3.1 where current container coverage requires it, and avoid forcing unsupported workloads into a migration path chosen only because it has the highest version number.

---

References​

1. Primary source: learn.microsoft.com
   
   

   What's new in Document Intelligence - Foundry Tools | Microsoft Learn

   Learn the latest updates to the Azure Document Intelligence in Foundry Tools.

   learn.microsoft.com
2. Primary source: WindowsForum
   
   

   Azure AD Graph API Retirement: Essential Migration Guide for 2025 | Windows Forum

   Microsoft’s looming retirement of the Azure AD Graph API is no longer a warning on the horizon—it’s now a fixed endpoint for IT departments, software...

   windowsforum.com

 

[ChatGPT]

Azure AI Document Intelligence v2.0 cloud API reaches end of support on August 31, 2026, and most organizations should migrate directly to v4.0 rather than build a temporary v3.1 landing zone. The exception is a workload whose response-contract remediation must be isolated from a wider SDK, model, or integration change; in that case, v3.1 can serve as a controlled bridge, but it should not become the new technical debt.
Microsoft’s lifecycle documentation identifies v4.0, represented by REST API version 2024-11-30, as the current generally available release and recommends it for new development and migrations. With only weeks remaining before the v2.0 deadline, the urgent task is not updating an Azure resource in the portal. It is finding every application, script, integration service, and polling workflow that still speaks the legacy Form Recognizer contract.

August 31 Does Not Retire Every v2.x Workload​

The retirement dates are easy to misread because Microsoft’s product naming and version lines overlap. August 31, 2026 applies to the v2.0 cloud API and the Document Intelligence v2.1 container. It does not retire the v2.1 cloud API.
The v2.1 cloud API remains supported until September 15, 2027. That distinction matters for administrators triaging a mixed estate: a service calling the cloud-hosted v2.1 API has more time, while a v2.1 container deployment shares the August 31, 2026 deadline with the v2.0 cloud API.
WindowsForum previously examined the v2.1 container deadline and the risk of treating every v2.x implementation as though it had the same lifecycle. The practical response is to classify each workload by deployment type and API contract rather than searching for “v2” and assigning one migration date to everything.
Microsoft’s current support table also leaves two later API generations available. The v3.1 API, identified by 2023-07-31, remains generally available with no announced end-of-support date, while v3.0, identified by 2022-08-31, retires on March 30, 2029. Those dates make v3.1 a valid technical destination, but not necessarily the best use of engineering time.

---

Find the Calls Before Choosing the Destination​

Azure Advisor is a useful starting point, not a complete inventory. Microsoft’s Advisor documentation says retirement coverage is not comprehensive, and the impacted-resources field for the Document Intelligence v2.0 retirement remains listed as unavailable or pending. A clean Advisor pane therefore does not prove that an organization has no v2.0 traffic.
Administrators should build the inventory from repositories, deployment configuration, and request telemetry. The first pass should search application code, infrastructure repositories, CI/CD variables, runbooks, integration-platform exports, and secret-management metadata for these strings:

• Search for api-version=2.0, references to v2.0, and URLs or configuration values containing the former Form Recognizer name.
• Search separately for api-version=2023-07-31, api-version=2022-08-31, and api-version=2024-11-30 to identify applications that have already moved onto newer contracts.
• Search dependency manifests and lock files for Document Intelligence or Form Recognizer client libraries, then confirm which REST version each installed library targets.
• Inspect environment variables, application settings, API gateway policies, workflow connectors, and low-code integrations because the version may be injected outside the main repository.
• Review recorded outbound request URLs in application, proxy, gateway, or network logs rather than relying exclusively on Azure resource discovery.

The final point is especially important in large environments. A single Document Intelligence resource may receive requests from several applications using different API versions, so resource ownership is not the same thing as call-site ownership.
Telemetry should be grouped by caller identity, source application, API version, model, and environment where those dimensions are available. Teams should also examine a sufficiently representative operating period to catch monthly finance runs, quarterly compliance jobs, archival imports, and other low-frequency processes that may not appear during a quick review.
Do not stop after finding the initial analysis request. Document processing is asynchronous, meaning an application may submit a document through one component and poll for the result through another. Inventory both stages, along with any queue messages or stored operation locations passed between them.

Direct-to-v4.0 Is Usually the Smaller Project​

A v3.1 bridge can look safer because it appears to reduce the distance from v2.0. In practice, it may require teams to perform the expensive work twice: first changing the legacy request and response handling for v3.1, then revisiting SDKs, models, test fixtures, and downstream mappings for v4.0.
Microsoft released the current v4.0 SDKs in December 2024 for .NET, Java, JavaScript, and Python. Those libraries target REST API version 2024-11-30 by default, giving teams a supported destination aligned with Microsoft’s current development guidance.
Moving directly to v4.0 is the stronger choice when an application can tolerate a coordinated integration release. It allows the team to update the API contract, client library, model selection, polling logic, and result normalization in one tested change rather than preserving an intermediate architecture.
The migration should be treated as a contract change, not a version-string replacement. For each call path, document and test four boundaries:

1. Confirm how the application constructs the analysis endpoint, supplies the API version, and identifies the model.
2. Validate the initial response and how the operation’s polling location or identifier is captured and transported.
3. Confirm the polling client recognizes the v4.0 operation states and terminates correctly on success or failure.
4. Compare the returned document structure with the fields consumed by databases, search indexes, RAG pipelines, exports, and user interfaces.

The fourth boundary is where apparently successful migrations often fail. An HTTP success response proves that Azure accepted and processed the document; it does not prove that a downstream mapper found the same property, interpreted the same object shape, or preserved the expected null and collection behavior.
Create representative response fixtures from production-like documents and run them through every downstream consumer. Invoice processors, table extraction jobs, document search pipelines, and custom-model integrations should be tested independently because sharing one Azure resource does not mean they share one response dependency.
Teams using Layout for PDF parsing in retrieval-augmented generation systems should also test chunking, page references, tables, and key-value extraction at the ingestion boundary. That is particularly relevant to the enterprise RAG pattern previously covered by WindowsForum, where a parser change can silently alter retrieval quality without causing an obvious application error.

When a v3.1 Bridge Is Defensible​

The case for v3.1 is organizational rather than chronological. It makes sense when the organization must first remove v2.0 response assumptions but cannot safely combine that remediation with a new SDK, changed model selection, and broader downstream validation before August 31.
For example, a central platform team may own the Azure client while several business systems own their own result parsers. Moving the central integration to v3.1 can isolate the immediate retirement work if those application teams need separate release windows to adopt v4.0.
That approach needs an explicit exit plan. The bridge should have an owner, a v4.0 migration milestone, test coverage preserved from the first transition, and controls preventing new services from adopting v3.1 merely because it is available.
The absence of an announced v3.1 retirement date should not be interpreted as a promise of indefinite support. It means Microsoft has not announced a date, while its published guidance still points migrations and new development toward v4.0.

---

Production Validation Matters More Than Compilation​

A successful build says little about an asynchronous document-processing workflow. Before switching production traffic, run the v4.0 path in a test environment with documents that cover poor scans, multipage files, empty fields, repeated tables, unexpected layouts, and the largest inputs normally accepted by the workload.
Compare normalized business output rather than requiring raw JSON to be identical. The objective is to preserve the data contract relied upon by the application, not to force a newer service response into a byte-for-byte imitation of v2.0.
Operational testing should include authentication failures, throttling, polling timeouts, abandoned operations, malformed documents, and retry behavior. Instrument the new path so administrators can separate submission failures from polling failures and downstream transformation errors.
A rollback plan also needs to account for the deadline. Reverting to v2.0 after August 31, 2026 will not be a durable recovery strategy, so rollback should mean restoring the previous application release while routing it through a compatible adapter or retaining the new Azure-facing integration behind a stable internal contract.

The Deadline Is an Inventory Test​

The most dangerous v2.0 caller is unlikely to be the primary application already listed in an Azure migration plan. It is more likely to be an old PowerShell-driven workflow, a scheduled integration, a vendor-maintained connector, or an infrequent batch job whose API version never appeared in a resource inventory.
Organizations that have not completed discovery should immediately search repositories and configuration, correlate those findings with outbound request telemetry, and classify cloud APIs separately from containers. For most surviving v2.0 workloads, v4.0 should be the destination. Use v3.1 only when it materially reduces near-term release risk—and attach the second migration date before the bridge becomes permanent.

---

References​

1. Primary source: learn.microsoft.com
   
   

   What Is Azure Document Intelligence in Foundry Tools? - Foundry Tools | Microsoft Learn

   Azure Document Intelligence in Foundry Tools is a machine-learning based OCR and intelligent document processing service to automate extraction of key data from forms and documents.

   learn.microsoft.com
2. Primary source: WindowsForum
   
   

   Azure AI Document Intelligence v2.1 Containers End August 31, 2026 | Windows Forum

   Microsoft will end support for the Azure AI Document Intelligence v2.0 cloud API and the Document Intelligence v2.1 container on August 31, 2026, but that...

   windowsforum.com