AI Foundry document analyzer service API version

Question

AI Foundry document analyzer service API version

Khoruzhiy, Maxim 0

Hi
I use AI Foundry Content Understanding in our workflows. The I build a Document Analyzer from a custom task (manually in AI Foundry GUI), it always becomes bound to API version '2025-05-01-preview'.

What should be done to get analyzer working in the scope of GA API ver 2025-11-01?

SRILAKSHMI C 19,735 Reputation points Microsoft External Staff Moderator

2026-06-09T07:10:05.9066667+00:00

Hi @Khoruzhiy, Maxim

Following up to see if the below answer was helpful. If this answers your query, please do click Accept Answer and Yes for was this answer helpful. And, if you have any further query do let us know.

Thank you!

2 answers

Your answer

SRILAKSHMI C 19,735 Reputation points Microsoft External Staff Moderator

2026-06-09T07:10:05.9066667+00:00

Hi @Khoruzhiy, Maxim

Following up to see if the below answer was helpful. If this answers your query, please do click Accept Answer and Yes for was this answer helpful. And, if you have any further query do let us know.

Thank you!

Answer 1

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!

SRILAKSHMI C 19,735 Reputation points Microsoft External Staff Moderator

2026-06-10T07:29:52.83+00:00

Hi @Khoruzhiy, Maxim

Just checking in to see if you have got a chance to see my response to your question in resolving the issue.

If you are still facing any further issues, please don't hesitate to reach out to us. We are happy to assist you.

Looking forward to your response and appreciate your time on this.

If you feel that your quires have been resolved, please accept the answer by clicking the "Upvote" and "Accept Answer" on the post.

Thank you!
Maxim Khoruzhiy 0 Reputation points

2026-06-16T08:16:34.7333333+00:00

Hi Srilakshmi

thank you for the comprehensive answer.
I actually found out that the GA ver of the api is used when the content understanding service is used from the new AI Foundry experience.
SRILAKSHMI C 19,735 Reputation points Microsoft External Staff Moderator

2026-06-16T09:10:28.8866667+00:00

Hi Maxim Khoruzhiy,

Thank you for sharing this update and for confirming your findings.

Yes, that aligns with what we are currently observing as the AI Foundry experience continues to evolve.

If you are using the new AI Foundry experience, Content Understanding resources and analyzers may indeed be created against the GA API version (2025-11-01). This suggests that the API version used can depend on the specific Foundry experience or workflow through which the analyzer is provisioned.

In other words, there appear to be two different behaviors:

Legacy/current custom task workflows may still provision analyzers using the preview API version (2025-05-01-preview).

The newer AI Foundry experience may provision analyzers directly against the GA API version (2025-11-01).

Thank you!
SRILAKSHMI C 19,735 Reputation points Microsoft External Staff Moderator

2026-06-17T07:27:29.48+00:00

Hi Maxim Khoruzhiy,

Following up to see if the above answer was helpful. If this answers your query, please do click Accept Answer and Yes for was this answer helpful. And, if you have any further query do let us know.

Thank you!
SRILAKSHMI C 19,735 Reputation points Microsoft External Staff Moderator

2026-06-18T06:39:28.3333333+00:00

Hi Maxim Khoruzhiy,

Just checking in to see if you have got a chance to see my response to your question in resolving the issue.

If you are still facing any further issues, please don't hesitate to reach out to us. We are happy to assist you.

Looking forward to your response and appreciate your time on this.

If you feel that your quires have been resolved, please accept the answer by clicking the "Upvote" and "Accept Answer" on the post.

Thank you!

Answer 2

Content Understanding analyzers created in the Foundry (classic) portal are bound to the preview API version 2025-05-01-preview and cannot be switched to the GA API in-place. To use the GA API version 2025-11-01, analyzers must be created and called via the GA endpoints instead of relying on the Foundry (classic) UI.

To get an analyzer working with the GA API 2025-11-01:

Create the analyzer using the GA REST API
- Use a PUT request against the GA API version when creating the analyzer:
```
     curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2025-11-01" \
       -H "Ocp-Apim-Subscription-Key: {key}" \
       -H "Content-Type: application/json" \
       -d @request_body.json
```
- The request_body.json defines the analyzer (schema, mode, inputs, etc.) according to the GA schema.
- The 201 Created response returns an Operation-Location header. Poll that URL (with api-version=2025-11-01) until the operation status is "succeeded".
Call the analyzer with GA operations
- For analysis, use the GA analyze or analyzeBinary operations with api-version=2025-11-01 as described in the migration guidance. For example, analyze now takes an inputs array with a URL to the file, and analyzeBinary is used for base64-encoded content in the request body.
Migrate from preview analyzers to GA
- Existing analyzers created via Foundry (classic) remain on 2025-05-01-preview. To move to GA, recreate equivalent analyzers using the GA API and update calling applications to use the new analyzer IDs and api-version=2025-11-01.
- When migrating, account for GA changes such as:
  - Use of analyzeBinary for inline file uploads.
  - Updated analyze request schema with an inputs array.
  - Optional confidence/grounding via estimateFieldSourceAndConfidence.
Prefer Foundry (new) or Content Understanding Studio for GA workflows
- Foundry (classic) is explicitly tied to 2025-05-01-preview and includes preview-only features like Pro mode.
- Foundry (new) and Content Understanding Studio are aligned with the GA API 2025-11-01 and should be used for new GA-based solutions.

In summary, analyzers created in the Foundry (classic) GUI will stay on 2025-05-01-preview. To work with 2025-11-01, create and manage analyzers via the GA REST API (or GA-aligned portals like Foundry (new)/Content Understanding Studio) and update workflows to call those GA analyzers.

References: