Migrate from Azure Content Understanding Preview to GA

Hello Wouter Schaekers,

Greetings! Thanks for raising this question in Q&A forum.

You have correctly identified the issue here. The official migration guide assumes you are starting from either Content Understanding Studio or the new Azure AI Foundry experience, but if your existing analyzers were built in Foundry Classic, there is a platform compatibility gap that the guide does not mention. Foundry Classic does not support the 2025-11-01 GA API, which is exactly why Step 3 in the guide fails with a BadRequest for you. In short, an in-place upgrade from Foundry Classic to GA is not a supported path and you will need to provision a fresh GA-compatible resource and recreate your analyzers there. The good news is this can be done cleanly with Bicep as you prefer, and your existing analyzer definitions can be exported as a starting point.

Here are the steps to handle this migration properly:

Step 1: Confirm you are on Foundry Classic

Before doing anything, verify your current setup by checking the portal URL you use to access Content Understanding. If it points to the older experience rather than ai.azure.com, you are on Foundry Classic. You can also cross-check using the comparison table in the official docs:

https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/foundry-vs-content-understanding-studio

Step 2: Provision a new GA-compatible resource via Bicep

Yes, you can absolutely provision a Content Understanding resource via Bicep. Use the Microsoft.CognitiveServices/accounts resource type with kind ContentUnderstanding. Here is a working template to get you started:

resource contentUnderstanding 'Microsoft.CognitiveServices/accounts@2024-04-01-preview' = {
  name: '<your-resource-name>'
  location: '<your-region>'
  kind: 'ContentUnderstanding'
  sku: {
    name: 'S0'
  }
  properties: {
    customSubDomainName: '<your-subdomain>'
    publicNetworkAccess: 'Enabled'
  }
}

Once this resource is deployed, you can immediately use the 2025-11-01 GA API against it.

Step 3: Export your existing analyzer definitions from Foundry Classic

Before rebuilding, pull your existing analyzer schemas from Foundry Classic so you have a reference. Use a GET call against the preview API:

GET https://<your-old-endpoint>/contentunderstanding/analyzers/<analyzer-id>?api-version=2025-05-01-preview

Save the returned JSON — you will use it as the blueprint for recreating the analyzer on the new GA resource.

Step 4: Review GA schema changes before recreating

There are some schema differences between the preview and GA API versions that you need to adjust before reusing your exported definition. Review the migration guide's schema change section carefully:

https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/how-to/migration-preview-to-ga

Step 5: Recreate your analyzers on the new GA resource

Using your adjusted definition from Step 4, create your analyzers on the new resource using the GA API:

PUT https://<your-new-endpoint>/contentunderstanding/analyzers/<analyzer-id>?api-version=2025-11-01

Test each analyzer thoroughly after creation to confirm parity with your Foundry Classic versions.

Step 6: Report the documentation gap to Microsoft

The official migration guide does not call out that Foundry Classic users cannot follow the standard upgrade path and must start fresh with a new resource. This will confuse many users in the same situation. Please use the feedback button at the bottom of the migration guide page to flag this gap so Microsoft can add a clear note for Foundry Classic users — it will save a lot of frustration for others.

If this answer helps you kindly accept the answer which will help others who have similar questions.

Best Regards,

Jerald Felix.