AI Foundry document analyzer service API version

Hello @Khoruzhiy, Maxim

Thank you for reaching out to Microsoft Q&A.

What you are currently observing is expected behavior for AI Foundry Content Understanding analyzers created from custom tasks through the current Foundry GUI experience.

At present, when a Document Analyzer is created through the AI Foundry portal using custom tasks, the analyzer is typically provisioned against the preview API contract:

2025-05-01-preview

Even though newer GA API versions such as:

2025-11-01

may already be available for the broader Content Understanding service surface, the current Foundry UI workflow is still generally bound to the preview analyzer/runtime version.

Because of this, there is currently no direct portal-side option to switch an existing analyzer from:

2025-05-01-preview → 2025-11-01

If you want the analyzer to operate against the GA API surface (2025-11-01), the recommended workaround at this time is to provision or update the analyzer directly through ARM/REST APIs while explicitly targeting the GA API version.

Example REST pattern:

PUT /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.DocumentIntelligence/analyzers/{analyzerName}?api-version=2025-11-01
{
 "properties": {
 /* analyzer/task definitions */
 }
}

Similarly, in ARM/Bicep templates, you would explicitly specify:

"apiVersion": "2025-11-01"

This approach provisions the analyzer against the GA API endpoint instead of the default preview API currently used by the Foundry GUI flow.

At the moment, the Foundry Content Understanding extension/UI itself has not yet fully transitioned to native GA analyzer provisioning. Once the portal experience is updated, the expectation is that customers will be able to:

• Select the GA API version directly in the UI

• Create analyzers natively against the GA surface

• Avoid the need for REST/ARM workarounds

Until then, using REST/ARM deployment targeting 2025-11-01 is the primary workaround for locking analyzers to the GA API version.

A few additional points to keep in mind:

• Existing preview-created analyzers may continue operating on the preview contract even after GA release

• In many Azure AI services, preview resources are not automatically migrated to GA versions

• In some cases, recreating the analyzer using the GA API version may be required

I would also recommend validating whether all specific analyzer capabilities you are using are already supported under the 2025-11-01 GA API surface.

Please refer this

Document Models – Analyze Document – API (GA 2024-11-30 v4.0): https://learn.microsoft.com/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v4.0%20(2024-11-30)&tabs=HTTP#documentcontentformat

Azure Document Intelligence in Foundry Tools (v4.0 GA overview): https://learn.microsoft.com/azure/ai-services/document-intelligence/overview?view=doc-intel-4.0.0

Azure Content Understanding in Foundry Tools (document analyzer capabilities): https://learn.microsoft.com/azure/ai-services/content-understanding/document/overview?wt.mc_id=knowledgesearch_inproduct_azure-cxp-community-insider#document-analyzer-capabilities

I Hope this helps. Do let me know if you have any further queries.

If this answers your query, please do click Accept Answer and Yes for was this answer helpful.

Thank you!