How to use Azure Content Understanding APIs?

Question

I have created resource with Document Intelligence and would like to use the contentunderstanding pre-built analyzer model. I am getting 401 error. Has anyone tried to use contentunderstanding via REST API? Please provide me the details on how to use this feature/product?

Answer 1

Hi Automation Agent

Azure Content Understanding is not the same service as the classic Azure Document Intelligence / Form Recognizer APIs. Even though it appears under “Document Intelligence” in the portal, Content Understanding is a Foundry‑based service with its own REST surface, analyzers, and authentication model. Calling Form Recognizer (/formrecognizer/…) or Document Intelligence (/documentintelligence/…) endpoints against a Content Understanding resource will result in 401 Unauthorized or 404 errors, even if the resource exists and keys look valid. [learn.microsoft.com]

Correct REST endpoint (most common 401 cause):

Content Understanding REST APIs must be called using the Foundry service root endpoint, not the project endpoint.

• Incorrect (will return 401): https://<foundry>.services.ai.azure.com/api/projects/<project>
• Correct: https://<foundry>.services.ai.azure.com/contentunderstanding/... This distinction is explicitly documented and is the number one reason customers see 401 errors when calling prebuilt analyzers. [gist.github.com]

Authentication model difference Unlike classic Document Intelligence, Content Understanding REST calls require Azure AD (Entra ID) Bearer token authentication. Using only Ocp-Apim-Subscription-Key (as with Form Recognizer) is not sufficient for analyzer execution calls and commonly results in 401 Unauthorized. The access token must be requested with the resource audience: https://cognitiveservices.azure.com. This requirement is explicitly documented for Content Understanding REST usage. [gist.github.com]

Example of correct authentication flow The supported flow is:

1. Obtain a Bearer token using Azure CLI or managed identity:

Shell

az account get-access-token \
 --resource https://cognitiveservices.azure.com \
 --query accessToken -o tsv

1. Call the Content Understanding REST API using:

Authorization: Bearer <access_token>

Using subscription keys alone is only supported for limited configuration calls, not for analyzer execution. [gist.github.com]

---

\Required Foundry model dependencies:

Content Understanding analyzers depend on Foundry model deployments. If the required models are not deployed and set as defaults, analyzer calls may fail with 401 or 403, even when authentication is correct. Microsoft documents that the following model deployments must exist and be configured as defaults:

• gpt-4.1
• gpt-4.1-mini
• text-embedding-3-large Defaults are configured via the /contentunderstanding/defaults REST API or through the Foundry portal. [learn.microsoft.com]

Region availability impacts authentication:

Content Understanding is not available in all Azure regions. If the resource is created in an unsupported region, REST calls may fail with authentication‑style errors (401/403) rather than a clear “region not supported” message. Microsoft currently documents limited supported regions such as Sweden Central, West US, and Australia East. [microsoftl....github.io]

Correct REST call pattern (prebuilt analyzer) A valid prebuilt analyzer call looks like:

Plain Text

http isn’t fully supported. Syntax highlighting is based on Plain Text.

POST https://<foundry>.services.ai.azure.com/contentunderstanding/analyzers/prebuilt-layout:analyze?api-version=2025-05-01-preview

Authorization: Bearer <token>

Content-Type: application/json

This pattern is different from analyzeDocument used in classic Document Intelligence and must follow the Content Understanding REST specification. [learn.microsoft.com], [learn.microsoft.com]

Microsoft repositioned Document Intelligence under Foundry Tools, and Content Understanding represents a new analyzer‑based architecture rather than an incremental update. Because the portal UX, resource naming, and branding still reference “Document Intelligence,” many customers incorrectly assume Form Recognizer APIs apply—leading directly to 401 errors. This architectural change is documented but easy to miss. [idp-software.com]

401 troubleshooting checklist If you see 401 Unauthorized, verify all of the following:

• You are calling the Foundry root endpoint, not the project endpoint
• The path starts with /contentunderstanding/
• You are using an Azure AD Bearer token, not only a subscription key
• Token audience is https://cognitiveservices.azure.com
• Required Foundry models are deployed and set as defaults
• The resource is in a supported region Missing any one of these will result in 401. [learn.microsoft.com], [gist.github.com]

References:

• Azure Cognitive Services Documentation
• Authentication to Azure Open AI service
• Quickstart: Use Azure Content Understanding in Foundry Tools REST API
• Deployment of models for Content Understanding I Hope this helps. Do let me know if you have any further queries.

Thankyou!

Answer 2

To use the Azure Content Understanding APIs, particularly the pre-built analyzer model, you need to ensure that you have set up everything correctly. Here are the steps to follow:

1. Ensure Proper Authentication: The 401 error typically indicates an authentication issue. Make sure that you are using the correct subscription key in your requests. This key should be included in the headers of your API calls.
   • Example header:

          -H "Ocp-Apim-Subscription-Key: {your_subscription_key}"
     

2. Set Up Your Resource: Confirm that you have created a Microsoft Foundry resource in a supported region. You can check this in the Azure portal under Foundry > Foundry.
3. Deploy Default Models: You need to set up default model deployments for your Content Understanding resource. This can be done through the Azure portal or using the REST API.
4. Using the REST API: You can make a request to the Content Understanding REST API to analyze content. Here’s an example of how to create an 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
   

   Replace {endpoint}, {analyzerId}, and {key} with your specific values.
5. Check Operation Status: After making a request, you will receive a 201 Created response, which includes an Operation-Location header. You can use this URL to track the status of your analyzer creation operation.

      curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2025-11-01" \
        -H "Ocp-Apim-Subscription-Key: {key}"
   

   This will return the status of the operation.

If you follow these steps and ensure that your authentication and resource setup are correct, you should be able to use the Content Understanding APIs without encountering a 401 error.