Microsoft Azure AI Foundry Operations API

openapi: 3.2.0
info:
  title: Document Intelligence (formerly Form Recognizer) Operations…
  version: '2024-11-30'
  description: Extracts content, layout, and structured data from documents.
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
security:
- ApiKeyAuth: []
- OAuth2Auth:
  - https://cognitiveservices.azure.com/.default
tags:
- name: Operations
paths:
  /operations:
    get:
      operationId: MiscellaneousOperations_ListOperations
      description: Lists all operations.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          headers:
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDocumentIntelligenceOperationDetails'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentIntelligenceErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
      tags:
      - Operations
      summary: Miscellaneous operations list operations
      x-summary-source: derived
  /operations/{operationId}:
    get:
      operationId: MiscellaneousOperations_GetDocumentModelBuildOperation
      description: Gets operation info.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: operationId
        in: path
        description: Operation ID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          headers:
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentModelBuildOperationDetails'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentIntelligenceErrorResponse'
      tags:
      - Operations
      summary: Miscellaneous operations get document model build operation
      x-summary-source: derived
components:
  schemas:
    DocumentModelBuildOperationDetails:
      type: object
      description: Get Operation response object.
      properties:
        result:
          $ref: '#/components/schemas/DocumentModelDetails'
          description: Operation result upon success.
      allOf:
      - $ref: '#/components/schemas/DocumentIntelligenceOperationDetails'
      x-ms-discriminator-value: documentModelBuild
    AzureBlobContentSource:
      type: object
      description: Azure Blob Storage content.
      properties:
        containerUrl:
          type: string
          format: uri
          description: Azure Blob Storage container URL.
        prefix:
          type: string
          description: Blob name prefix.
      required:
      - containerUrl
    DocumentIntelligenceOperationStatus:
      type: string
      description: Operation status.
      enum:
      - notStarted
      - running
      - failed
      - succeeded
      - canceled
      - skipped
      x-ms-enum:
        name: DocumentIntelligenceOperationStatus
        modelAsString: true
        values:
        - name: notStarted
          value: notStarted
          description: The operation has not started yet.
        - name: running
          value: running
          description: The operation is in progress.
        - name: failed
          value: failed
          description: The operation has failed.
        - name: succeeded
          value: succeeded
          description: The operation has succeeded.
        - name: canceled
          value: canceled
          description: The operation has been canceled.
        - name: skipped
          value: skipped
          description: The operation has been skipped.
    DocumentIntelligenceWarning:
      type: object
      description: The error object.
      properties:
        code:
          type: string
          description: One of a server-defined set of warning codes.
        message:
          type: string
          description: A human-readable representation of the warning.
        target:
          type: string
          description: The target of the error.
      required:
      - code
      - message
    DocumentFieldSchema:
      type: object
      description: Description of the field semantic schema using a JSON Schema style syntax.
      properties:
        type:
          $ref: '#/components/schemas/DocumentFieldType'
          description: Semantic data type of the field value.
        description:
          type: string
          description: Field description.
          maxLength: 4096
        example:
          type: string
          description: Example field content.
        items:
          $ref: '#/components/schemas/DocumentFieldSchema'
          description: Field type schema of each array element.
        properties:
          type: object
          description: Named sub-fields of the object field.
          additionalProperties:
            $ref: '#/components/schemas/DocumentFieldSchema'
      required:
      - type
    DocumentBuildMode:
      type: string
      description: Custom document model build mode.
      enum:
      - template
      - neural
      x-ms-enum:
        name: DocumentBuildMode
        modelAsString: true
        values:
        - name: template
          value: template
          description: Target documents with similar visual templates.
        - name: neural
          value: neural
          description: Support documents with diverse visual templates.
    DocumentModelDetails:
      type: object
      description: Document model info.
      properties:
        modelId:
          type: string
          description: Unique document model name.
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9._~-]{1,63}$
          x-ms-mutability:
          - read
          - create
        description:
          type: string
          description: Document model description.
          maxLength: 4096
        createdDateTime:
          type: string
          format: date-time
          description: Date and time (UTC) when the document model was created.
          readOnly: true
        expirationDateTime:
          type: string
          format: date-time
          description: Date and time (UTC) when the document model will expire.
          readOnly: true
        modifiedDateTime:
          type: string
          format: date-time
          description: Date and time (UTC) when the document model was last modified.
          readOnly: true
        apiVersion:
          type: string
          description: API version used to create this document model.
          readOnly: true
        tags:
          type: object
          description: List of key-value tag attributes associated with the document model.
          additionalProperties:
            type: string
        buildMode:
          $ref: '#/components/schemas/DocumentBuildMode'
          description: Custom document model build mode.
          readOnly: true
        azureBlobSource:
          $ref: '#/components/schemas/AzureBlobContentSource'
          description: 'Azure Blob Storage location containing the training data.  Either

            azureBlobSource or azureBlobFileListSource must be specified.'
          readOnly: true
        azureBlobFileListSource:
          $ref: '#/components/schemas/AzureBlobFileListContentSource'
          description: 'Azure Blob Storage file list specifying the training data.  Either

            azureBlobSource or azureBlobFileListSource must be specified.'
          readOnly: true
        classifierId:
          type: string
          description: For composed models, the custom classifier to split and classify the input file.
        split:
          type: string
          description: For composed models, the file splitting behavior.
          default: none
          enum:
          - auto
          - none
          - perPage
          x-ms-enum:
            name: SplitMode
            modelAsString: true
            values:
            - name: auto
              value: auto
              description: Automatically split file into documents.
            - name: none
              value: none
              description: Treat the entire file as a single document.
            - name: perPage
              value: perPage
              description: Treat each page in the file as a separate document.
        docTypes:
          type: object
          description: Supported document types.
          additionalProperties:
            $ref: '#/components/schemas/DocumentTypeDetails'
          readOnly: true
        warnings:
          type: array
          description: List of warnings encountered while building the model.
          items:
            $ref: '#/components/schemas/DocumentIntelligenceWarning'
          readOnly: true
        trainingHours:
          type: number
          format: float
          description: Number of V100-equivalent GPU hours consumed for model training.
          readOnly: true
      required:
      - modelId
      - createdDateTime
    DocumentAnalysisFeature:
      type: string
      description: Document analysis features to enable.
      enum:
      - ocrHighResolution
      - languages
      - barcodes
      - formulas
      - keyValuePairs
      - styleFont
      - queryFields
      x-ms-enum:
        name: DocumentAnalysisFeature
        modelAsString: true
        values:
        - name: ocrHighResolution
          value: ocrHighResolution
          description: Perform OCR at a higher resolution to handle documents with fine print.
        - name: languages
          value: languages
          description: Enable the detection of the text content language.
        - name: barcodes
          value: barcodes
          description: Enable the detection of barcodes in the document.
        - name: formulas
          value: formulas
          description: Enable the detection of mathematical expressions in the document.
        - name: keyValuePairs
          value: keyValuePairs
          description: Enable the detection of general key value pairs (form fields) in the document.
        - name: styleFont
          value: styleFont
          description: Enable the recognition of various font styles.
        - name: queryFields
          value: queryFields
          description: Enable the extraction of additional fields via the queryFields query parameter.
    PagedDocumentIntelligenceOperationDetails:
      type: object
      description: Paged collection of DocumentIntelligenceOperationDetails items
      properties:
        value:
          type: array
          description: The DocumentIntelligenceOperationDetails items on this page
          items:
            $ref: '#/components/schemas/DocumentIntelligenceOperationDetails'
        nextLink:
          type: string
          format: uri
          description: The link to the next page of items
      required:
      - value
    OperationKind:
      type: string
      description: Type of operation.
      enum:
      - documentModelBuild
      - documentModelCompose
      - documentModelCopyTo
      - documentClassifierCopyTo
      - documentClassifierBuild
      x-ms-enum:
        name: OperationKind
        modelAsString: true
        values:
        - name: documentModelBuild
          value: documentModelBuild
          description: Build a new custom document model.
        - name: documentModelCompose
          value: documentModelCompose
          description: Compose a new custom document model from existing models.
        - name: documentModelCopyTo
          value: documentModelCopyTo
          description: 'Copy an existing document model to potentially a different resource, region, or

            subscription.'
        - name: documentClassifierCopyTo
          value: documentClassifierCopyTo
          description: 'Copy an existing document classifier to potentially a different resource, region, or

            subscription.'
        - name: documentClassifierBuild
          value: documentClassifierBuild
          description: Build a new custom classifier model.
    DocumentIntelligenceErrorResponse:
      type: object
      description: Error response object.
      properties:
        error:
          $ref: '#/components/schemas/DocumentIntelligenceError'
          description: Error info.
      required:
      - error
    DocumentIntelligenceInnerError:
      type: object
      description: An object containing more specific information about the error.
      properties:
        code:
          type: string
          description: One of a server-defined set of error codes.
        message:
          type: string
          description: A human-readable representation of the error.
        innererror:
          $ref: '#/components/schemas/DocumentIntelligenceInnerError'
          description: Inner error.
    DocumentTypeDetails:
      type: object
      description: Document type info.
      properties:
        description:
          type: string
          description: Document model description.
          maxLength: 4096
        buildMode:
          $ref: '#/components/schemas/DocumentBuildMode'
          description: Custom document model build mode.
        fieldSchema:
          type: object
          description: Description of the document semantic schema using a JSON Schema style syntax.
          additionalProperties:
            $ref: '#/components/schemas/DocumentFieldSchema'
        fieldConfidence:
          type: object
          description: Estimated confidence for each field.
          additionalProperties:
            format: float
            type: number
        modelId:
          type: string
          description: Document model to use for analyzing documents with specified type.
          maxLength: 64
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9._~-]{1,63}$
        confidenceThreshold:
          type: number
          format: float
          description: Only perform analysis if docType confidence is above threshold.
        features:
          type: array
          description: List of optional analysis features.
          items:
            $ref: '#/components/schemas/DocumentAnalysisFeature'
        queryFields:
          type: array
          description: List of additional fields to extract.  Ex. "NumberOfGuests,StoreNumber"
          items:
            type: string
        maxDocumentsToAnalyze:
          type: integer
          format: int32
          description: Maximum number of documents of specified type to analyze.  Default=all.
    DocumentIntelligenceError:
      type: object
      description: The error object.
      properties:
        code:
          type: string
          description: One of a server-defined set of error codes.
        message:
          type: string
          description: A human-readable representation of the error.
        target:
          type: string
          description: The target of the error.
        details:
          type: array
          description: An array of details about specific errors that led to this reported error.
          items:
            $ref: '#/components/schemas/DocumentIntelligenceError'
        innererror:
          $ref: '#/components/schemas/DocumentIntelligenceInnerError'
          description: An object containing more specific information than the current object about the error.
      required:
      - code
      - message
    DocumentIntelligenceOperationDetails:
      type: object
      description: Operation info.
      properties:
        operationId:
          type: string
          description: Operation ID
          x-ms-mutability:
          - read
          - create
        status:
          $ref: '#/components/schemas/DocumentIntelligenceOperationStatus'
          description: Operation status.  notStarted, running, completed, or failed
        percentCompleted:
          type: integer
          format: int32
          description: Operation progress (0-100).
          minimum: 0
          maximum: 100
        createdDateTime:
          type: string
          format: date-time
          description: Date and time (UTC) when the operation was created.
        lastUpdatedDateTime:
          type: string
          format: date-time
          description: Date and time (UTC) when the status was last updated.
        kind:
          $ref: '#/components/schemas/OperationKind'
          description: Type of operation.
        resourceLocation:
          type: string
          format: uri
          description: URL of the resource targeted by this operation.
        apiVersion:
          type: string
          description: API version used to create this operation.
        tags:
          type: object
          description: List of key-value tag attributes associated with the document model.
          additionalProperties:
            type: string
        error:
          $ref: '#/components/schemas/DocumentIntelligenceError'
          description: Encountered error.
      discriminator:
        propertyName: kind
      required:
      - operationId
      - status
      - createdDateTime
      - lastUpdatedDateTime
      - kind
      - resourceLocation
    AzureBlobFileListContentSource:
      type: object
      description: File list in Azure Blob Storage.
      properties:
        containerUrl:
          type: string
          format: uri
          description: Azure Blob Storage container URL.
        fileList:
          type: string
          description: Path to a JSONL file within the container specifying a subset of documents.
      required:
      - containerUrl
      - fileList
    DocumentFieldType:
      type: string
      description: Semantic data type of the field value.
      enum:
      - string
      - date
      - time
      - phoneNumber
      - number
      - integer
      - selectionMark
      - countryRegion
      - signature
      - array
      - object
      - currency
      - address
      - boolean
      - selectionGroup
      x-ms-enum:
        name: DocumentFieldType
        modelAsString: true
        values:
        - name: string
          value: string
          description: Plain text.
        - name: date
          value: date
          description: Date, normalized to ISO 8601 (YYYY-MM-DD) format.
        - name: time
          value: time
          description: Time, normalized to ISO 8601 (hh:mm:ss) format.
        - name: phoneNumber
          value: phoneNumber
          description: Phone number, normalized to E.164 (+{CountryCode}{SubscriberNumber}) format.
        - name: number
          value: number
          description: Floating point number, normalized to double precision floating point.
        - name: integer
          value: integer
          description: Integer number, normalized to 64-bit signed integer.
        - name: selectionMark
          value: selectionMark
          description: Is field selected?
        - name: countryRegion
          value: countryRegion
          description: Country/region, normalized to ISO 3166-1 alpha-3 format (ex. USA).
        - name: signature
          value: signature
          description: Is signature present?
        - name: array
          value: array
          description: List of subfields of the same type.
        - name: object
          value: object
          description: Named list of subfields of potentially different types.
        - name: currency
          value: currency
          description: Currency amount with optional currency symbol and unit.
        - name: address
          value: address
          description: Parsed address.
        - name: boolean
          value: boolean
          description: Boolean value, normalized to true or false.
        - name: selectionGroup
          value: selectionGroup
          description: Array of selected string values.
  parameters:
    Azure.Core.ClientRequestIdHeader:
      name: x-ms-client-request-id
      in: header
      description: An opaque, globally-unique, client-generated string identifier for the request.
      required: false
      x-ms-parameter-location: method
      x-ms-client-name: clientRequestId
      schema:
        type: string
        format: uuid
    Azure.Core.Foundations.ApiVersionParameter:
      name: api-version
      in: query
      description: The API version to use for this operation.
      required: true
      x-ms-parameter-location: method
      x-ms-client-name: apiVersion
      schema:
        type: string
        minLength: 1
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            https://cognitiveservices.azure.com/.default: ''
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/token
x-ms-parameterized-host:
  hostTemplate: '{endpoint}/documentintelligence'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    in: path
    description: The Document Intelligence service endpoint.
    required: true
    type: string
    format: uri
    x-ms-skip-url-encoding: true
x-ms-paths:
  /documentClassifiers/{classifierId}:analyze?_overload=classifyDocument:
    post:
      operationId: DocumentClassifiers_ClassifyDocument
      description: Classifies document with document classifier.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/DocumentClassifierAnalyzeRequestParams.classifierId'
      - $ref: '#/components/parameters/DocumentClassifierAnalyzeRequestParams.stringIndexType'
      - $ref: '#/components/parameters/DocumentClassifierAnalyzeRequestParams.split'
      - $ref: '#/components/parameters/DocumentClassifierAnalyzeRequestParams.pages'
      - name: classifyRequest
        in: body
        description: Classify request parameters.
        required: true
        schema:
          $ref: '#/components/schemas/ClassifyDocumentRequest'
      responses:
        '202':
          description: The request has been accepted for processing, but processing has not yet completed.
          headers:
            Operation-Location:
              type: string
              format: uri
              description: The location of an instance of AnalyzeOperation
            Retry-After:
              type: integer
              format: int32
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/components/schemas/DocumentIntelligenceErrorResponse'
      x-ms-long-running-operation: true
  /documentModels/{modelId}:analyze?_overload=analyzeDocument:
    post:
      operationId: DocumentModels_AnalyzeDocument
      description: Analyzes document with document model.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/DocumentModelAnalyzeRequestParams.modelId'
      - $ref: '#/components/parameters/DocumentModelAnalyzeRequestParams.pages'
      - $ref: '#/components/parameters/DocumentModelAnalyzeRequestParams.locale'
      - $ref: '#/components/parameters/DocumentModelAnalyzeRequestParams.stringIndexType'
      - $ref: '#/components/parameters/DocumentModelAnalyzeRequestParams.features'
      - $ref: '#/components/parameters/DocumentModelAnalyzeRequestParams.queryFields'
      - $ref: '#/components/parameters/DocumentModelAnalyzeRequestParams.outputContentFormat'
      - $ref: '#/components/parameters/DocumentModelAnalyzeRequestParams.output'
      - name: analyzeRequest
        in: body
        description: Analyze request parameters.
        required: true
        schema:
          $ref: '#/components/schemas/AnalyzeDocumentRequest'
      responses:
        '202':
          description: The request has been accepted for processing, but processing has not yet completed.
          headers:
            Operation-Location:
              type: string
              format: uri
              description: The location of an instance of AnalyzeOperation
            Retry-After:
              type: integer
              format: int32
              description: The Retry-After header can indicate how long the client should wait before polling the operation status.
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/components/schemas/DocumentIntelligenceErrorResponse'
      x-ms-long-running-operation: true
  /operations/{operationId}?_overload=getDocumentClassifierBuildOperation:
    get:
      operationId: MiscellaneousOperations_GetDocumentClassifierBuildOperation
      description: Gets operation info.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: operationId
        in: path
        description: Operation ID
        required: true
        type: string
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/components/schemas/DocumentClassifierBuildOperationDetails'
          headers:
            x-ms-client-request-id:
              type: string
              format: uuid
              description: An opaque, globally-unique, client-generated string identifier for the request.
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/components/schemas/DocumentIntelligenceErrorResponse'
  /operations/{operationId}?_overload=getDocumentClassifierCopyToOperation:
    get:
      operationId: MiscellaneousOperations_GetDocumentClassifierCopyToOperation
      description: Gets operation info.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: operationId
        in: path
        description: Operation ID
        required: true
        type: string
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/components/schemas/DocumentClassifierCopyToOperationDetails'
          headers:
            x-ms-client-request-id:
              type: string
              format: uuid
              description: An opaque, globally-unique, client-generated string identifier for the request.
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/components/schemas/DocumentIntelligenceErrorResponse'
  /operations/{operationId}?_overload=getDocumentModelComposeOperation:
    get:
      operationId: MiscellaneousOperations_GetDocumentModelComposeOperation
      description: Gets operation info.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: operationId
        in: path
        description: Operation ID
        required: true
        type: string
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/components/schemas/DocumentModelComposeOperationDetails'
          headers:
            x-ms-client-request-id:
              type: string
              format: uuid
              description: An opaque, globally-unique, client-generated string identifier for the request.
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/components/schemas/DocumentIntelligenceErrorResponse'
  /operations/{operationId}?_overload=getDocumentModelCopyToOperation:
    get:
      operationId: MiscellaneousOperations_GetDocumentModelCopyToOperation
      description: Gets operation info.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: operationId
        in: path
        description: Operation ID
        required: true
        type: string
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/components/schemas/DocumentModelCopyToOperationDetails'
          headers:
            x-ms-client-request-id:
              type: string
              format: uuid
              description: An opaque, globally-unique, client-generated string identifier for the request.
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/components/schemas/DocumentIntelligenceErrorResponse'
  /operations/{operationId}?_overload=getOperation:
    get:
      operationId: MiscellaneousOperations_GetOperation
      description: Gets operation info.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: operationId
        in: path
        description: Operation ID
        required: true
        type: string
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/components/schemas/DocumentIntelligenceOperationDetails'
          headers:
            x-ms-client-request-id:
              type: string
              format: uuid
              description: An opaque, globally-unique, client-generated string identifier for the request.
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/components/schemas/DocumentIntelligenceErrorResponse'