Document Intelligence Guide

This guide explains how to call Azure Document Intelligence through the platform gateway, including the one configuration change that usually surprises developers: the software development kit must send the subscription key in the header name expected by the platform gateway.

API Key Header Configuration

Why api-key?

The platform uses a single Azure gateway service for application programming interfaces in front of several services, including language models, document processing, search, and storage. Because that gateway can only use one subscription key header name consistently, the documentation standardises on api-key.

The platform uses api-key because:

• SDK Compatibility: OpenAI SDK and other AI service libraries expect api-key
• Industry Standard: api-key is a more widely recognized header name than APIM-specific headers
• Developer Experience: Reduces confusion by using a consistent, familiar header across all services

SDK Configuration Examples

JavaScript/TypeScript (@azure-rest/ai-document-intelligence)

When using the @azure-rest/ai-document-intelligence npm package, configure the client to use api-key header:

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";

const endpoint = "https://apim-gateway.azure-api.net/tenant/documentintelligence";
const apiKey = "your-apim-subscription-key";

// Configure client with custom API key header name
const client = DocumentIntelligence(endpoint, { key: apiKey }, {
  credentials: {
    apiKeyHeaderName: "api-key",  // Override default "Ocp-Apim-Subscription-Key"
  },
});

// Use the client normally
const result = await client.path("/documentModels/{modelId}:analyze", "prebuilt-read")
  .post({
    contentType: "application/json",
    body: {
      urlSource: "https://example.com/document.pdf"
    }
  });

Python (azure-ai-documentintelligence)

from azure.ai.documentintelligence import DocumentIntelligenceClient
from azure.core.credentials import AzureKeyCredential
from azure.core.pipeline.policies import HeadersPolicy

endpoint = "https://apim-gateway.azure-api.net/tenant/documentintelligence"
api_key = "your-apim-subscription-key"

# Create custom headers policy to use api-key header
headers_policy = HeadersPolicy()
headers_policy.add_header("api-key", api_key)

# Create client with custom policy
client = DocumentIntelligenceClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(api_key),
    headers_policy=headers_policy
)

# Alternatively, use custom header directly in requests
# Note: Some SDK versions may require different configuration approaches

.NET (Azure.AI.DocumentIntelligence)

using Azure;
using Azure.AI.DocumentIntelligence;
using Azure.Core.Pipeline;

string endpoint = "https://apim-gateway.azure-api.net/tenant/documentintelligence";
string apiKey = "your-apim-subscription-key";

// Create client options with custom header
var options = new DocumentIntelligenceClientOptions();
options.AddPolicy(new AddHeaderPolicy("api-key", apiKey), HttpPipelinePosition.PerCall);

// Create client
var client = new DocumentIntelligenceClient(
    new Uri(endpoint),
    new AzureKeyCredential(apiKey),
    options
);

// Custom policy to add api-key header
public class AddHeaderPolicy : HttpPipelineSynchronousPolicy
{
    private readonly string _headerName;
    private readonly string _headerValue;

    public AddHeaderPolicy(string headerName, string headerValue)
    {
        _headerName = headerName;
        _headerValue = headerValue;
    }

    public override void OnSendingRequest(HttpMessage message)
    {
        message.Request.Headers.Add(_headerName, _headerValue);
    }
}

Direct REST API (curl)

If SDK configuration is complex or unavailable, use direct REST API calls:

# Analyze document with prebuilt-read model
curl -X POST "https://apim-gateway.azure-api.net/tenant/documentintelligence/documentModels/prebuilt-read:analyze?api-version=2024-07-31-preview" \
  -H "api-key: your-apim-subscription-key" \
  -H "Content-Type: application/json" \
  -d '{
    "urlSource": "https://example.com/document.pdf"
  }'

# Alternative: Use query parameter
curl -X POST "https://apim-gateway.azure-api.net/tenant/documentintelligence/documentModels/prebuilt-read:analyze?api-version=2024-07-31-preview&api-key=your-apim-subscription-key" \
  -H "Content-Type: application/json" \
  -d '{
    "urlSource": "https://example.com/document.pdf"
  }'

Async Operations & Polling

Document Intelligence async operations (document analysis, model training) return a 202 Accepted response with an Operation-Location header for status polling.

Backend returns:
  Operation-Location: https://tenant-docint.cognitiveservices.azure.com/documentintelligence/documentModels/prebuilt-read/analyzeResults/abc123

APIM rewrites to:
  Operation-Location: https://apim-gateway.azure-api.net/tenant/documentintelligence/documentModels/prebuilt-read/analyzeResults/abc123

Troubleshooting

Additional Resources

• Azure Document Intelligence Documentation
• @azure-rest/ai-document-intelligence npm package
• azure-ai-documentintelligence Python package
• Azure.AI.DocumentIntelligence NuGet package