Content Analyzers - Create Or Replace

Service:: Azure AI Services

API Version:: 2025-11-01

Create a new analyzer asynchronously.

PUT {endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2025-11-01

With optional parameters:

PUT {endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2025-11-01&allowReplace={allowReplace}

URI Parameters

Name	In	Required	Type	Description
analyzerId	path	True	string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9._-]{1,64}$	The unique identifier of the analyzer.
endpoint	path	True	string (uri)	Content Understanding service endpoint.
api-version	query	True	string minLength: 1	The API version to use for this operation.
allowReplace	query		boolean	Allow the operation to replace an existing resource.

Request Header

Name	Required	Type	Description
x-ms-client-request-id		string (uuid)	An opaque, globally-unique, client-generated string identifier for the request.

Request Body

Name	Type	Description
baseAnalyzerId	string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9._-]{1,64}$	The analyzer to incrementally train from.
config	ContentAnalyzerConfig	Analyzer configuration settings.
description	string	A description of the analyzer.
dynamicFieldSchema	boolean	Indicates whether the result may contain additional fields outside of the defined schema.
fieldSchema	ContentFieldSchema	The schema of fields to extracted.
knowledgeSources	KnowledgeSource[]: LabeledDataKnowledgeSource[]	Additional knowledge sources used to enhance the analyzer.
models	object	Mapping of model roles to specific model names. Ex. { "completion": "gpt-4.1", "embedding": "text-embedding-3-large" }.
processingLocation	ProcessingLocation	The location where the data may be processed. Defaults to global.
tags	object	Tags associated with the analyzer.

Responses

Name	Type	Description
200 OK	ContentAnalyzer	The request has succeeded. Headers Operation-Location: string x-ms-client-request-id: string
201 Created	ContentAnalyzer	The request has succeeded and a new resource has been created as a result. Headers Operation-Location: string x-ms-client-request-id: string
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

ContentAnalyzer

The request has succeeded.

Headers

Operation-Location: string
x-ms-client-request-id: string

201 Created

ContentAnalyzer

The request has succeeded and a new resource has been created as a result.

Headers

Operation-Location: string
x-ms-client-request-id: string

Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Key-based authentication using the access key of the Azure resource.

Type: apiKey
In: header

EntraIdToken

Microsoft Entra ID OAuth2 authentication using an access token.

Type: oauth2
Flow: accessCode
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize
Token URL: https://login.microsoftonline.com/common/oauth2/token

Scopes

Name	Description
https://cognitiveservices.azure.com/.default

Examples

Create or Replace Analyzer

Sample request

HTTP

PUT {endpoint}/contentunderstanding/analyzers/myAnalyzer?api-version=2025-11-01

{
  "description": "My analyzer",
  "tags": {
    "createdBy": "John"
  },
  "baseAnalyzerId": "prebuilt-document",
  "config": {
    "enableFormula": false,
    "returnDetails": true
  },
  "fieldSchema": {
    "name": "MyForm",
    "description": "My form",
    "fields": {
      "Company": {
        "type": "string",
        "description": "Name of company."
      }
    },
    "definitions": {}
  },
  "knowledgeSources": [
    {
      "kind": "labeledData",
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer",
      "prefix": "trainingData",
      "fileListPath": "trainingData/fileList.jsonl"
    }
  ]
}

Sample response

Status code:: 200

Operation-Location: https://myendpoint.cognitiveservices.azure.com/contentunderstanding/analyzers/myAnalyzer/operations/3b31320d-8bab-4f88-b19c-2322a7f11034?api-version=2025-11-01

{
  "analyzerId": "myAnalyzer",
  "description": "My analyzer",
  "tags": {
    "createdBy": "John"
  },
  "status": "creating",
  "createdAt": "2025-05-01T18:46:36.051Z",
  "lastModifiedAt": "2025-05-01T18:46:36.051Z",
  "baseAnalyzerId": "prebuilt-document",
  "config": {
    "locales": null,
    "enableOcr": true,
    "enableLayout": true,
    "enableFormula": false,
    "returnDetails": true
  },
  "fieldSchema": {
    "name": "MyForm",
    "description": "My form",
    "fields": {
      "Company": {
        "type": "string",
        "description": "Name of company."
      }
    },
    "definitions": {}
  },
  "knowledgeSources": [
    {
      "kind": "labeledData",
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer",
      "prefix": "trainingData",
      "fileListPath": "trainingData/fileList.jsonl"
    }
  ]
}

Status code:: 201

Operation-Location: https://myendpoint.cognitiveservices.azure.com/contentunderstanding/analyzers/myAnalyzer/operations/3b31320d-8bab-4f88-b19c-2322a7f11034?api-version=2025-11-01

{
  "analyzerId": "myAnalyzer",
  "description": "My analyzer",
  "tags": {
    "createdBy": "John"
  },
  "status": "creating",
  "createdAt": "2025-05-01T18:46:36.051Z",
  "lastModifiedAt": "2025-05-01T18:46:36.051Z",
  "baseAnalyzerId": "prebuilt-document",
  "config": {
    "locales": null,
    "enableOcr": true,
    "enableLayout": true,
    "enableFormula": false,
    "returnDetails": true
  },
  "fieldSchema": {
    "name": "MyForm",
    "description": "My form",
    "fields": {
      "Company": {
        "type": "string",
        "description": "Name of company."
      }
    },
    "definitions": {}
  },
  "knowledgeSources": [
    {
      "kind": "labeledData",
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer",
      "prefix": "trainingData",
      "fileListPath": "trainingData/fileList.jsonl"
    }
  ]
}

Definitions

Name	Description
AnnotationFormat	Representation format of annotations in analyze result markdown.
Azure.Core.Foundations.Error	The error object.
Azure.Core.Foundations.ErrorResponse	A response containing error details.
Azure.Core.Foundations.InnerError	An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.
ChartFormat	Representation format of charts in analyze result markdown.
ContentAnalyzer	Analyzer that extracts content and fields from multimodal documents.
ContentAnalyzerConfig	Configuration settings for an analyzer.
ContentAnalyzerStatus	Status of a resource.
ContentCategoryDefinition	Content category definition.
ContentFieldDefinition	Definition of the field using a JSON Schema like syntax.
ContentFieldSchema	Schema of fields to be extracted from documents.
ContentFieldType	Semantic data type of the field value.
GenerationMethod	Generation method.
KnowledgeSourceKind	Knowledge source kind.
LabeledDataKnowledgeSource	Labeled data knowledge source.
ProcessingLocation	The location where the data may be processed. Defaults to global.
SupportedModels	Chat completion and embedding models supported by the analyzer.
TableFormat	Representation format of tables in analyze result markdown.

AnnotationFormat

Enumeration

Representation format of annotations in analyze result markdown.

Value	Description
none	Do not represent annotations.
markdown	Represent basic annotation information using markdown formatting.

Azure.Core.Foundations.Error

Object

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.InnerError	An object containing more specific information than the current object about the error.
message	string	A human-readable representation of the error.
target	string	The target of the error.

Azure.Core.Foundations.ErrorResponse

Object

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

Object

An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.

Name	Type	Description
code	string	One of a server-defined set of error codes.
innererror	Azure.Core.Foundations.InnerError	Inner error.

ChartFormat

Enumeration

Representation format of charts in analyze result markdown.

Value	Description
chartJs	Represent charts as Chart.js code blocks.
markdown	Represent charts as markdown tables.