Microsoft Azure Custom API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Custom API
tags:
- name: Custom
paths:
  /custom/models:
    post:
      summary: Microsoft Azure Train Custom Model
      description: Create and train a custom model. The request must include a source parameter that is either an externally accessible Azure storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be under the source folder or sub folders under it. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. Other type of content is ignored.
      operationId: microsoftAzureTraincustommodelasync
      responses:
        '201':
          description: Request is queued successfully.
          headers:
            Location:
              description: Location and ID of the model being trained. The status of model training is specified in the status property at the model location.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Train custom model:
          $ref: ./examples/TrainBatch.json
        Train custom model with subfolder filter options:
          $ref: ./examples/TrainBatchWithSubFolders.json
      x-ms-long-running-operation: true
      tags:
      - Custom
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainRequest'
        description: Training request parameters.
        required: true
  /custom/models/{modelId}:
    get:
      summary: Microsoft Azure Get Custom Model
      description: Get detailed information about a custom model.
      operationId: microsoftAzureGetcustommodel
      parameters:
      - name: modelId
        in: path
        description: Model identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: includeKeys
        in: query
        description: Include list of extracted keys in model information.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Get custom model:
          $ref: ./examples/GetModel.json
      tags:
      - Custom
    delete:
      summary: Microsoft Azure Delete Custom Model
      description: Mark model for deletion. Model artifacts will be permanently removed within a predetermined period.
      operationId: microsoftAzureDeletecustommodel
      parameters:
      - name: modelId
        in: path
        description: Model identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Successfully marked model for deletion. Model artifacts will be removed within a predefined time period.
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Delete custom model:
          $ref: ./examples/DeleteModel.json
      tags:
      - Custom
  /custom/models/{modelId}/analyze:
    post:
      summary: Microsoft Azure Analyze Form
      description: Extract key-value pairs, tables, and semantic values from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff' or 'image/bmp'. Alternatively, use 'application/json' type to specify the location (Uri or local path) of the document to be analyzed.
      operationId: microsoftAzureAnalyzewithcustommodel
      parameters:
      - name: modelId
        in: path
        description: Model identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: includeTextDetails
        in: query
        description: Include text lines and element references in the result.
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Pages'
      - $ref: '#/components/parameters/FileStream'
      responses:
        '202':
          description: Request is queued successfully.
          headers:
            Operation-Location:
              description: URL containing the resultId used to track the progress and obtain the result of the analyze operation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Analyze form with custom model:
          $ref: ./examples/AnalyzeBatch.json
      x-ms-long-running-operation: true
      tags:
      - Custom
  /custom/models/{modelId}/analyzeResults/{resultId}:
    get:
      summary: Microsoft Azure Get Analyze Form Result
      description: Obtain current status and the result of the analyze form operation.
      operationId: microsoftAzureGetanalyzeformresult
      parameters:
      - name: modelId
        in: path
        description: Model identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: resultId
        in: path
        description: Analyze operation result identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeOperationResult'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Get analyze form result:
          $ref: ./examples/AnalyzeOperationResult.json
      tags:
      - Custom
  /custom/models/{modelId}/copy:
    post:
      summary: Microsoft Azure Copy Custom Model
      description: Copy custom model stored in this resource (the source) to user specified target Form Recognizer resource.
      operationId: microsoftAzureCopycustommodel
      parameters:
      - name: modelId
        in: path
        description: Model identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Copy request is queued successfully.
          headers:
            Operation-Location:
              description: URL containing the resultId used to track the progress and obtain the result of the copy operation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Copy custom model:
          $ref: ./examples/CopyModel.json
      x-ms-long-running-operation: true
      tags:
      - Custom
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyRequest'
        description: Copy request parameters.
        required: true
  /custom/models/{modelId}/copyResults/{resultId}:
    get:
      summary: Microsoft Azure Get Custom Model Copy Result
      description: Obtain current status and the result of a custom model copy operation.
      operationId: microsoftAzureGetcustommodelcopyresult
      parameters:
      - name: modelId
        in: path
        description: Model identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: resultId
        in: path
        description: Copy operation result identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CopyOperationResult'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Get copy custom model result:
          $ref: ./examples/CopyOperationResult.json
        Get copy custom model result with failures:
          $ref: ./examples/CopyOperationResultWithErrors.json
      tags:
      - Custom
  /custom/models/copyAuthorization:
    post:
      summary: Microsoft Azure Generate Copy Authorization
      description: Generate authorization to copy a model into the target Form Recognizer resource.
      operationId: microsoftAzureGeneratemodelcopyauthorization
      responses:
        '201':
          description: Copy request is authorized successfully.
          headers:
            Location:
              description: Location and ID of the model being copied. The status of model copy is specified in the status property at the model location.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CopyAuthorizationResult'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Copy custom model:
          $ref: ./examples/CopyModelAuthorization.json
      tags:
      - Custom
components:
  schemas:
    TextLine:
      description: An object representing an extracted text line.
      type: object
      required:
      - text
      - boundingBox
      - words
      properties:
        text:
          description: The text content of the line.
          type: string
        boundingBox:
          description: Bounding box of an extracted line.
          $ref: '#/components/schemas/BoundingBox'
        words:
          description: List of words in the text line.
          type: array
          items:
            $ref: '#/components/schemas/TextWord'
        appearance:
          description: Text appearance properties.
          $ref: '#/components/schemas/Appearance'
    CopyRequest:
      description: Request parameter to copy an existing custom model from the source resource to a target resource referenced by the resource ID.
      required:
      - targetResourceId
      - targetResourceRegion
      - copyAuthorization
      type: object
      properties:
        targetResourceId:
          description: Azure Resource Id of the target Form Recognizer resource where the model is copied to.
          maxLength: 1024
          type: string
          pattern: ^/subscriptions/[^/]*/resourceGroups/[^/]*/providers/Microsoft.CognitiveServices/accounts/[^/]*$
          x-ms-azure-resource: true
        targetResourceRegion:
          description: Location of the target Azure resource. A valid Azure region name supported by Cognitive Services.
          type: string
          pattern: ^[a-z0-9]+$
          minLength: 1
          maxLength: 24
        copyAuthorization:
          description: Entity that encodes claims to authorize the copy request.
          $ref: '#/components/schemas/CopyAuthorizationResult'
    FormFieldsReport:
      description: Report for a custom model training field.
      type: object
      required:
      - fieldName
      - accuracy
      properties:
        fieldName:
          description: Training field name.
          type: string
        accuracy:
          description: Estimated extraction accuracy for this field.
          type: number
    ElementReference:
      description: Reference to a line, word or selection mark.
      type: string
    BoundingBox:
      description: Quadrangle bounding box, with coordinates specified relative to the top-left of the original image. The eight numbers represent the four points, clockwise from the top-left corner relative to the text orientation. For image, the (x, y) coordinates are measured in pixels. For PDF, the (x, y) coordinates are measured in inches.
      type: array
      minItems: 8
      maxItems: 8
      items:
        type: number
    Attributes:
      description: Optional model attributes.
      type: object
      properties:
        isComposed:
          description: 'Is this model composed? (default: false).'
          type: boolean
          default: false
    ErrorInformation:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
        message:
          type: string
    AnalyzeOperationResult:
      description: Status and result of the queued analyze operation.
      type: object
      required:
      - status
      - createdDateTime
      - lastUpdatedDateTime
      properties:
        status:
          description: Operation status.
          $ref: '#/components/schemas/OperationStatus'
        createdDateTime:
          format: date-time
          description: Date and time (UTC) when the analyze operation was submitted.
          type: string
        lastUpdatedDateTime:
          format: date-time
          description: Date and time (UTC) when the status was last updated.
          type: string
        analyzeResult:
          description: Results of the analyze operation.
          $ref: '#/components/schemas/AnalyzeResult'
    DataTableCell:
      description: Information about the extracted cell in a table.
      type: object
      required:
      - rowIndex
      - columnIndex
      - text
      - boundingBox
      - confidence
      properties:
        rowIndex:
          description: Row index of the cell.
          type: integer
          minimum: 0
        columnIndex:
          description: Column index of the cell.
          type: integer
          minimum: 0
        rowSpan:
          description: Number of rows spanned by this cell.
          type: integer
          minimum: 1
          default: 1
        columnSpan:
          description: Number of columns spanned by this cell.
          type: integer
          minimum: 1
          default: 1
        text:
          description: Text content of the cell.
          type: string
        boundingBox:
          description: Bounding box of the cell.
          $ref: '#/components/schemas/BoundingBox'
        confidence:
          description: Confidence value.
          $ref: '#/components/schemas/Confidence'
        elements:
          description: When includeTextDetails is set to true, a list of references to the text elements constituting this table cell.
          type: array
          items:
            $ref: '#/components/schemas/ElementReference'
        isHeader:
          description: Is the current cell a header cell?
          type: boolean
          default: false
        isFooter:
          description: Is the current cell a footer cell?
          type: boolean
          default: false
    TrainResult:
      description: Custom model training result.
      type: object
      required:
      - trainingDocuments
      properties:
        trainingDocuments:
          description: List of the documents used to train the model and any errors reported in each document.
          type: array
          items:
            $ref: '#/components/schemas/TrainingDocumentInfo'
        fields:
          description: List of fields used to train the model and the train operation error reported by each.
          type: array
          items:
            $ref: '#/components/schemas/FormFieldsReport'
        averageModelAccuracy:
          description: Average accuracy.
          type: number
        modelId:
          description: Model identifier.
          type: string
          format: uuid
        errors:
          description: Errors returned during the training operation.
          type: array
          items:
            $ref: '#/components/schemas/ErrorInformation'
    ReadResult:
      description: Text extracted from a page in the input document.
      type: object
      required:
      - page
      - angle
      - width
      - height
      - unit
      properties:
        page:
          description: The 1-based page number in the input document.
          type: integer
          minimum: 1
        angle:
          description: The general orientation of the text in clockwise direction, measured in degrees between (-180, 180].
          type: number
          maximum: 180
          exclusiveMinimum: -180
        width:
          description: The width of the image/PDF in pixels/inches, respectively.
          type: number
          minimum: 0
        height:
          description: The height of the image/PDF in pixels/inches, respectively.
          type: number
          minimum: 0
        unit:
          description: The unit used by the width, height and boundingBox properties. For images, the unit is "pixel". For PDF, the unit is "inch".
          type: string
          enum:
          - pixel
          - inch
          x-ms-enum:
            name: LengthUnit
            modelAsString: false
        lines:
          description: When includeTextDetails is set to true, a list of recognized text lines. The maximum number of lines returned is 300 per page. The lines are sorted top to bottom, left to right, although in certain cases proximity is treated with higher priority. As the sorting order depends on the detected text, it may change across images and OCR version updates. Thus, business logic should be built upon the actual line location instead of order.
          type: array
          items:
            $ref: '#/components/schemas/TextLine'
        selectionMarks:
          description: List of selection marks extracted from the page.
          type: array
          items:
            $ref: '#/components/schemas/SelectionMark'
    CopyAuthorizationResult:
      description: Request parameter that contains authorization claims for copy operation.
      required:
      - modelId
      - accessToken
      - expirationDateTimeTicks
      type: object
      properties:
        modelId:
          description: Model identifier.
          type: string
        accessToken:
          description: Token claim used to authorize the request.
          type: string
        expirationDateTimeTicks:
          description: The time when the access token expires. The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time.
          type: integer
          format: int64
    FieldValue:
      description: Recognized field value.
      type: object
      required:
      - type
      properties:
        type:
          description: Type of field value.
          $ref: '#/components/schemas/FieldValueType'
        valueString:
          description: String value.
          type: string
        valueDate:
          description: Date value.
          format: date
          type: string
        valueTime:
          description: Time value.
          format: time
          type: string
        valuePhoneNumber:
          description: Phone number value.
          type: string
        valueNumber:
          description: Floating point value.
          type: number
        valueInteger:
          description: Integer value.
          type: integer
        valueArray:
          description: Array of field values.
          type: array
          items:
            $ref: '#/components/schemas/FieldValue'
        valueObject:
          description: Dictionary of named field values.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldValue'
        valueSelectionMark:
          description: Selection mark value.
          type: string
          enum:
          - selected
          - unselected
        valueGender:
          description: 'Gender value: M, F, or X.'
          type: string
          enum:
          - M
          - F
          - X
        valueCountry:
          description: 3-letter country code (ISO 3166-1 alpha-3).
          type: string
        text:
          description: Text content of the extracted field.
          type: string
        boundingBox:
          description: Bounding box of the field value, if appropriate.
          $ref: '#/components/schemas/BoundingBox'
        confidence:
          description: Confidence score.
          $ref: '#/components/schemas/Confidence'
        elements:
          description: When includeTextDetails is set to true, a list of references to the text elements constituting this field.
          type: array
          items:
            $ref: '#/components/schemas/ElementReference'
        page:
          description: The 1-based page number in the input document.
          type: integer
          minimum: 1
    SelectionMark:
      description: Information about the extracted selection mark.
      type: object
      required:
      - boundingBox
      - confidence
      - state
      properties:
        boundingBox:
          description: Bounding box of the selection mark.
          $ref: '#/components/schemas/BoundingBox'
        confidence:
          description: Confidence value.
          $ref: '#/components/schemas/Confidence'
        state:
          description: State of the selection mark.
          type: string
          enum:
          - selected
          - unselected
    FieldValueType:
      type: string
      description: Semantic data type of the field value.
      enum:
      - string
      - date
      - time
      - phoneNumber
      - number
      - integer
      - array
      - object
      - selectionMark
      - gender
      - country
      x-ms-enum:
        name: FieldValueType
        modelAsString: false
    KeysResult:
      description: Keys extracted by the custom model.
      type: object
      required:
      - clusters
      properties:
        clusters:
          description: Object mapping clusterIds to a list of keys.
          type: object
          additionalProperties:
            type: array
            uniqueItems: true
            items:
              type: string
    CopyOperationResult:
      description: Status and result of the queued copy operation.
      type: object
      required:
      - status
      - createdDateTime
      - lastUpdatedDateTime
      properties:
        status:
          description: Operation status.
          $ref: '#/components/schemas/OperationStatus'
        createdDateTime:
          format: date-time
          description: Date and time (UTC) when the copy operation was submitted.
          type: string
        lastUpdatedDateTime:
          format: date-time
          description: Date and time (UTC) when the status was last updated.
          type: string
        copyResult:
          description: Results of the copy operation.
          $ref: '#/components/schemas/CopyResult'
    CopyResult:
      description: Custom model copy result.
      type: object
      required:
      - modelId
      properties:
        modelId:
          description: Identifier of the target model.
          type: string
          format: uuid
        errors:
          description: Errors returned during the copy operation.
          type: array
          items:
            $ref: '#/components/schemas/ErrorInformation'
    SourcePath:
      description: Uri or local path to source data.
      type: object
      properties:
        source:
          description: File source path.
          maxLength: 2048
          minLength: 0
          type: string
    TrainSourceFilter:
      description: Filter to apply to the documents in the source path for training.
      type: object
      properties:
        prefix:
          description: A case-sensitive prefix string to filter documents in the source path for training. For example, when using a Azure storage blob Uri, use the prefix to restrict sub folders for training.
          maxLength: 1024
          minLength: 0
          type: string
        includeSubFolders:
          description: A flag to indicate if sub folders within the set of prefix folders will also need to be included when searching for content to be preprocessed.
          type: boolean
          default: false
    ModelName:
      description: 'Optional user defined model name (max length: 1024).'
      type: string
    TrainRequest:
      description: Request parameter to train a new custom model.
      required:
      - source
      type: object
      properties:
        source:
          description: Source path containing the training documents.
          maxLength: 2048
          minLength: 0
          type: string
        sourceFilter:
          $ref: '#/components/schemas/TrainSourceFilter'
          description: Filter to apply to the documents in the source path for training.
        useLabelFile:
          description: Use label file for training a model.
          type: boolean
          default: false
        modelName:
          $ref: '#/components/schemas/ModelName'
    OperationStatus:
      type: string
      description: Status of the queued operation.
      enum:
      - notStarted
      - running
      - succeeded
      - failed
      x-ms-enum:
        name: OperationStatus
        modelAsString: false
    TextWord:
      description: An object representing a word.
      type: object
      required:
      - boundingBox
      - text
      properties:
        text:
          description: The text content of the word.
          type: string
        boundingBox:
          description: Bounding box of an extracted word.
          $ref: '#/components/schemas/BoundingBox'
        confidence:
          description: Confidence value.
          $ref: '#/components/schemas/Confidence'
    AnalyzeResult:
      description: Analyze operation result.
      type: object
      required:
      - version
      - readResults
      properties:
        version:
          description: Version of schema used for this result.
          type: string
        readResults:
          description: Text extracted from the input.
          type: array
          items:
            $ref: '#/components/schemas/ReadResult'
        pageResults:
          description: Page-level information extracted from the input.
          type: array
          items:
            $ref: '#/components/schemas/PageResult'
        documentResults:
          description: Document-level information extracted from the input.
          type: array
          items:
            $ref: '#/components/schemas/DocumentResult'
        errors:
          description: List of errors reported during the analyze operation.
          type: array
          items:
            $ref: '#/components/schemas/ErrorInformation'
    KeyValueElement:
      description: Information about the extracted key or value in a key-value pair.
      type: object
      required:
      - text
      properties:
        type:
          $ref: '#/components/schemas/KeyValueType'
        text:
          description: The text content of the key or value.
          type: string
        boundingBox:
          description: Bounding box of the key or value.
          $ref: '#/components/schemas/BoundingBox'
        elements:
          description: When includeTextDetails is set to true, a list of references to the text elements constituting this key or value.
          type: array
          items:
            $ref: '#/components/schemas/ElementReference'
    Appearance:
      description: An object representing the appearance of the text line.
      type: object
      required:
      - style
      properties:
        style:
          description: An object representing the style of the text line.
          type: object
          $ref: '#/components/schemas/Style'
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorInformation'
    Model:
      description: Response to the get custom model operation.
      type: object
      required:
      - modelInfo
      properties:
        modelInfo:
          $ref: '#/components/schemas/ModelInfo'
        keys:
          $ref: '#/components/schemas/KeysResult'
        trainResult:
          description: Training result for custom model.
          $ref: '#/components/schemas/TrainResult'
        composedTrainResults:
          type: array
          description: Training result for composed model.
          items:
            $ref: '#/components/schemas/TrainResult'
    ModelInfo:
      description: Basic custom model information.
      type: object
      required:
      - modelId
      - status
      - createdDateTime
      - lastUpdatedDateTime
      properties:
        modelId:
          description: Model identifier.
          type: string
          format: uuid
        status:
          description: Status of the model.
          enum:
          - creating
          - ready
          - invalid
          type: string
          x-ms-enum:
            name: ModelStatus
            modelAsString: false
        createdDateTime:
          format: date-time
          description: Date and time (UTC) when the model was created.
          type: string
        lastUpdatedDateTime:
          format: date-time
          description: Date and time (UTC) when the status was last updated.
          type: string
        modelName:
          $ref: '#/components/schemas/ModelName'
        attributes:
          $ref: '#/components/schemas/Attributes'
    DataTable:
      description: Information about the extracted table contained in a page.
      type: object
      required:
      - rows
      - columns
      - cells
      - boundingBox
      properties:
        rows:
          description: Number of rows.
          type: integer
          minimum: 1
        columns:
          description: Number of columns.
          type: integer
          minimum: 1
        cells:
          description: List of cells contained in the table.
          type: array
          items:
            $ref: '#/components/schemas/DataTableCell'
        boundingBox:
          description: Bounding box of the table.
          $ref: '#/components/schemas/BoundingBox'
    KeyValuePair:
      description: Information about the extracted key-value pair.
      type: object
      required:
      - key
      - value
      - confidence
      properties:
        label:
          description: A user defined label for the key/value pair entry.
          type: string
        key:
          description: Information about the extracted key in a key-value pair.
          $ref: '#/components/schemas/KeyValueElement'
        value:
          description: Information about the extracted value in a key-value pair.
          $ref: '#/components/schemas/KeyValueElement'
        confidence:
          description: Confidence value.
          $ref: '#/components/schemas/Confidence'
    Style:
      description: An object representing the style of the text line.
      type: object
      required:
      - name
 

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure/refs/heads/main/openapi/microsoft-azure-custom-api-openapi.yml