{
  "swagger": "2.0",
  "schemes": [
    "https"
  ],
  "host": "azure.local",
  "info": {
    "description": "Extracts information from forms and images into structured data based on a model created by a set of representative training forms.",
    "title": "Form Recognizer Client",
    "version": "1.0-preview",
    "x-apisguru-categories": [
      "cloud"
    ],
    "x-logo": {
      "url": "https://api.apis.guru/v2/cache/logo/https_assets.onestore.ms_cdnfiles_onestorerolling-1606-01000_shell_v3_images_logo_microsoft.png"
    },
    "x-origin": [
      {
        "format": "swagger",
        "url": "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/cognitiveservices/data-plane/FormRecognizer/preview/v1.0/FormRecognizer.json",
        "version": "2.0"
      }
    ],
    "x-preferred": false,
    "x-providerName": "azure.com",
    "x-serviceName": "cognitiveservices-FormRecognizer",
    "x-tags": [
      "Azure",
      "Microsoft"
    ]
  },
  "produces": [
    "application/json"
  ],
  "securityDefinitions": {
    "apim_key": {
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key",
      "type": "apiKey"
    }
  },
  "security": [
    {
      "apim_key": []
    }
  ],
  "parameters": {
    "Endpoint": {
      "description": "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).",
      "in": "path",
      "name": "Endpoint",
      "required": true,
      "type": "string",
      "x-ms-parameter-location": "client",
      "x-ms-skip-url-encoding": true
    }
  },
  "paths": {
    "/custom/models": {
      "get": {
        "consumes": [],
        "description": "Get information about all trained custom models",
        "operationId": "GetCustomModels",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "$ref": "#/definitions/ModelsResult"
            }
          },
          "default": {
            "description": "Response entity accompanying non-successful responses containing additional details about the error.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "summary": "Get Models",
        "x-ms-examples": {
          "Get Model from id": {
            "parameters": {
              "Content-Type": "application/json",
              "Endpoint": "{Endpoint}",
              "Ocp-Apim-Subscription-Key": "{API key}",
              "body": {},
              "id": "{Model Id}"
            },
            "responses": {
              "200": {
                "body": {
                  "models": [
                    {
                      "createdDateTime": "2019-05-01T10:53:21+00:00",
                      "lastUpdatedDateTime": "2019-05-01T10:53:23+00:00",
                      "modelId": "f973e3c1-1148-43bb-bea8-49d0603ab3a8",
                      "status": "ready"
                    },
                    {
                      "createdDateTime": "2019-04-30T21:39:41+00:00",
                      "lastUpdatedDateTime": "2019-04-30T21:39:44+00:00",
                      "modelId": "8dd53a98-bc73-43da-8533-60183824eb8e",
                      "status": "ready"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/custom/models/{id}": {
      "delete": {
        "consumes": [],
        "description": "Delete model artifacts.",
        "operationId": "DeleteCustomModel",
        "parameters": [
          {
            "description": "The identifier of the model to delete.",
            "format": "uuid",
            "in": "path",
            "name": "id",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully removed model artifacts."
          },
          "default": {
            "description": "Response entity accompanying non-successful responses containing additional details about the error.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "summary": "Delete Model",
        "x-ms-examples": {
          "Get Model from id": {
            "parameters": {
              "Content-Type": "application/json",
              "Endpoint": "{Endpoint}",
              "Ocp-Apim-Subscription-Key": "{API key}",
              "body": {},
              "id": "{Model Id}"
            },
            "responses": {
              "204": {}
            }
          }
        }
      },
      "get": {
        "consumes": [],
        "description": "Get information about a model.",
        "operationId": "GetCustomModel",
        "parameters": [
          {
            "description": "Model identifier.",
            "format": "uuid",
            "in": "path",
            "name": "id",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "$ref": "#/definitions/ModelResult"
            }
          },
          "default": {
            "description": "Response entity accompanying non-successful responses containing additional details about the error.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "summary": "Get Model",
        "x-ms-examples": {
          "Get Model from id": {
            "parameters": {
              "Content-Type": "application/json",
              "Endpoint": "{Endpoint}",
              "Ocp-Apim-Subscription-Key": "{API key}",
              "body": {},
              "id": "{Model Id}"
            },
            "responses": {
              "200": {
                "body": {
                  "createdDateTime": "2019-05-01T10:53:21+00:00",
                  "lastUpdatedDateTime": "2019-05-01T10:53:23+00:00",
                  "modelId": "f973e3c1-1148-43bb-bea8-49d0603ab3a8",
                  "status": "ready"
                }
              }
            }
          }
        }
      }
    },
    "/custom/models/{id}/analyze": {
      "post": {
        "consumes": [
          "application/pdf",
          "image/jpeg",
          "image/png",
          "multipart/form-data"
        ],
        "description": "Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON.",
        "operationId": "AnalyzeWithCustomModel",
        "parameters": [
          {
            "description": "Model Identifier to analyze the document with.",
            "format": "uuid",
            "in": "path",
            "name": "id",
            "required": true,
            "type": "string"
          },
          {
            "description": "An optional list of known keys to extract the values for.",
            "in": "query",
            "items": {
              "type": "string"
            },
            "name": "keys",
            "required": false,
            "type": "array",
            "uniqueItems": false
          },
          {
            "description": "A pdf document or image (jpg,png) file to analyze.",
            "in": "formData",
            "name": "form_stream",
            "required": true,
            "type": "file"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "$ref": "#/definitions/AnalyzeResult"
            }
          },
          "default": {
            "description": "Response entity accompanying non-successful responses containing additional details about the error.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "summary": "Analyze Form",
        "x-ms-examples": {
          "Get Model from id": {
            "parameters": {
              "Content-Type": "application/json",
              "Endpoint": "{Endpoint}",
              "Ocp-Apim-Subscription-Key": "{API key}",
              "body": {
                "formData": {}
              },
              "form_stream": "{Image or Pdf file stream}",
              "id": "{Model Id}"
            },
            "responses": {
              "200": {
                "body": {
                  "errors": [
                    {
                      "errorMessage": "Page1: Field not extracted"
                    }
                  ],
                  "pages": [
                    {
                      "clusterId": 0,
                      "height": 800,
                      "keyValuePairs": [
                        {
                          "key": [
                            {
                              "boundingBox": [
                                57.4,
                                683.1,
                                100.5,
                                683.1,
                                100.5,
                                673.7,
                                57.4,
                                673.7
                              ],
                              "text": "Address:"
                            }
                          ],
                          "value": [
                            {
                              "boundingBox": [
                                57.4,
                                672.2,
                                126.6,
                                672.2,
                                126.6,
                                658.9,
                                57.4,
                                658.9
                              ],
                              "confidence": 0.9,
                              "text": "1 Microsoft Way"
                            }
                          ]
                        }
                      ],
                      "number": 1,
                      "tables": [
                        {
                          "columns": [
                            {
                              "entries": [
                                [
                                  {
                                    "boundingBox": [
                                      305.6,
                                      692.1,
                                      403.5,
                                      692.1,
                                      403.5,
                                      684.2,
                                      305.6,
                                      684.2
                                    ],
                                    "confidence": 0.9,
                                    "text": "38772349"
                                  }
                                ]
                              ],
                              "header": [
                                {
                                  "boundingBox": [
                                    38.5,
                                    585.2,
                                    113.4,
                                    585.2,
                                    113.4,
                                    575.8,
                                    38.5,
                                    575.8
                                  ],
                                  "text": "InvoiceNumber"
                                }
                              ]
                            }
                          ],
                          "id": "table_0"
                        }
                      ],
                      "width": 600
                    }
                  ],
                  "status": "success"
                }
              }
            }
          }
        }
      }
    },
    "/custom/models/{id}/keys": {
      "get": {
        "consumes": [],
        "description": "Retrieve the keys that were\r\n extracted during the training of the specified model.",
        "operationId": "GetExtractedKeys",
        "parameters": [
          {
            "description": "Model identifier.",
            "format": "uuid",
            "in": "path",
            "name": "id",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "$ref": "#/definitions/KeysResult"
            }
          },
          "default": {
            "description": "Response entity accompanying non-successful responses containing additional details about the error.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "summary": "Get Keys",
        "x-ms-examples": {
          "Get Keys from Model": {
            "parameters": {
              "Content-Type": "application/json",
              "Endpoint": "{Endpoint}",
              "Ocp-Apim-Subscription-Key": "{API key}",
              "body": {},
              "id": "{Model Id}"
            },
            "responses": {
              "200": {
                "body": {
                  "clusters": {
                    "0": [
                      "Invoice",
                      "123112313"
                    ],
                    "1": [
                      "Please remit payment to:",
                      "Microsoft"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/custom/train": {
      "post": {
        "consumes": [
          "application/json"
        ],
        "description": "Create and train a custom model. The train 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\r\n 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 directly under the source folder. Subfolders are not supported. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'.\"\r\n Other type of content is ignored.",
        "operationId": "TrainCustomModel",
        "parameters": [
          {
            "description": "Request object for training.",
            "in": "body",
            "name": "trainRequest",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TrainRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "$ref": "#/definitions/TrainResult"
            }
          },
          "default": {
            "description": "Response entity accompanying non-successful responses containing additional details about the error.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "summary": "Train Model",
        "x-ms-examples": {
          "Train new model example": {
            "parameters": {
              "Content-Type": "application/json",
              "Endpoint": "{Endpoint}",
              "Ocp-Apim-Subscription-Key": "{API key}",
              "body": {},
              "trainRequest": {
                "source": "/input/data"
              }
            },
            "responses": {
              "200": {
                "body": {
                  "errors": [],
                  "modelId": "ad1901b6-ddaa-4249-8938-3f03f65cc893",
                  "trainingDocuments": [
                    {
                      "documentName": "0.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    },
                    {
                      "documentName": "1.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    },
                    {
                      "documentName": "2.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    },
                    {
                      "documentName": "3.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    },
                    {
                      "documentName": "4.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    }
                  ]
                }
              }
            }
          },
          "Train new model example, subfolder filter options": {
            "parameters": {
              "Content-Type": "application/json",
              "Endpoint": "{Endpoint}",
              "Ocp-Apim-Subscription-Key": "{API key}",
              "body": {},
              "trainRequest": {
                "source": "/input/data",
                "sourceFilter": {
                  "includeSubFolders": false,
                  "prefix": ""
                }
              }
            },
            "responses": {
              "200": {
                "body": {
                  "errors": [],
                  "modelId": "ad1901b6-ddaa-4249-8938-3f03f65cc893",
                  "trainingDocuments": [
                    {
                      "documentName": "0.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    },
                    {
                      "documentName": "1.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    },
                    {
                      "documentName": "2.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    },
                    {
                      "documentName": "3.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    },
                    {
                      "documentName": "4.pdf",
                      "errors": [],
                      "pages": 1,
                      "status": "success"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "AnalyzeResult": {
      "description": "Analyze API call result.",
      "properties": {
        "errors": {
          "description": "List of errors reported during the analyze\r\noperation.",
          "items": {
            "$ref": "#/definitions/FormOperationError"
          },
          "type": "array",
          "uniqueItems": false
        },
        "pages": {
          "description": "Page level information extracted in the analyzed\r\ndocument.",
          "items": {
            "$ref": "#/definitions/ExtractedPage"
          },
          "type": "array",
          "uniqueItems": false
        },
        "status": {
          "description": "Status of the analyze operation.",
          "enum": [
            "success",
            "partialSuccess",
            "failure"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "ErrorInformation": {
      "properties": {
        "code": {
          "type": "string"
        },
        "innerError": {
          "$ref": "#/definitions/InnerError"
        },
        "message": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "ErrorResponse": {
      "properties": {
        "error": {
          "$ref": "#/definitions/ErrorInformation"
        }
      },
      "type": "object"
    },
    "ExtractedKeyValuePair": {
      "description": "Representation of a key-value pair as a list\r\nof key and value tokens.",
      "properties": {
        "key": {
          "description": "List of tokens for the extracted key in a key-value pair.",
          "items": {
            "$ref": "#/definitions/ExtractedToken"
          },
          "type": "array",
          "uniqueItems": false
        },
        "value": {
          "description": "List of tokens for the extracted value in a key-value pair.",
          "items": {
            "$ref": "#/definitions/ExtractedToken"
          },
          "type": "array",
          "uniqueItems": false
        }
      },
      "type": "object"
    },
    "ExtractedPage": {
      "description": "Extraction information of a single page in a\r\nwith a document.",
      "properties": {
        "clusterId": {
          "description": "Cluster identifier.",
          "format": "int32",
          "type": "integer"
        },
        "height": {
          "description": "Height of the page (in pixels).",
          "format": "int32",
          "type": "integer"
        },
        "keyValuePairs": {
          "description": "List of Key-Value pairs extracted from the page.",
          "items": {
            "$ref": "#/definitions/ExtractedKeyValuePair"
          },
          "type": "array",
          "uniqueItems": false
        },
        "number": {
          "description": "Page number.",
          "format": "int32",
          "type": "integer"
        },
        "tables": {
          "description": "List of Tables and their information extracted from the page.",
          "items": {
            "$ref": "#/definitions/ExtractedTable"
          },
          "type": "array",
          "uniqueItems": false
        },
        "width": {
          "description": "Width of the page (in pixels).",
          "format": "int32",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "ExtractedTable": {
      "description": "Extraction information about a table\r\ncontained in a page.",
      "properties": {
        "columns": {
          "description": "List of columns contained in the table.",
          "items": {
            "$ref": "#/definitions/ExtractedTableColumn"
          },
          "type": "array",
          "uniqueItems": false
        },
        "id": {
          "description": "Table identifier.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "ExtractedTableColumn": {
      "description": "Extraction information of a column in\r\na table.",
      "properties": {
        "entries": {
          "description": "Extracted text for each cell of a column. Each cell\r\nin the column can have a list of one or more tokens.",
          "items": {
            "items": {
              "$ref": "#/definitions/ExtractedToken"
            },
            "type": "array",
            "uniqueItems": false
          },
          "type": "array",
          "uniqueItems": false
        },
        "header": {
          "description": "List of extracted tokens for the column header.",
          "items": {
            "$ref": "#/definitions/ExtractedToken"
          },
          "type": "array",
          "uniqueItems": false
        }
      },
      "type": "object"
    },
    "ExtractedToken": {
      "description": "Canonical representation of single extracted text.",
      "properties": {
        "boundingBox": {
          "description": "Bounding box of the extracted text. Represents the\r\nlocation of the extracted text as a pair of\r\ncartesian co-ordinates. The co-ordinate pairs are arranged by\r\ntop-left, top-right, bottom-right and bottom-left endpoints box\r\nwith origin reference from the bottom-left of the page.",
          "items": {
            "format": "double",
            "type": "number"
          },
          "type": "array",
          "uniqueItems": false
        },
        "confidence": {
          "description": "A measure of accuracy of the extracted text.",
          "format": "double",
          "type": "number"
        },
        "text": {
          "description": "String value of the extracted text.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "FormDocumentReport": {
      "properties": {
        "documentName": {
          "description": "Reference to the data that the report is for.",
          "type": "string"
        },
        "errors": {
          "description": "List of errors per page.",
          "items": {
            "type": "string"
          },
          "type": "array",
          "uniqueItems": false
        },
        "pages": {
          "description": "Total number of pages trained on.",
          "format": "int32",
          "type": "integer"
        },
        "status": {
          "description": "Status of the training operation.",
          "enum": [
            "success",
            "partialSuccess",
            "failure"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "FormOperationError": {
      "description": "Error reported during an operation.",
      "properties": {
        "errorMessage": {
          "description": "Message reported during the train operation.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "InnerError": {
      "properties": {
        "requestId": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "KeysResult": {
      "description": "Result of an operation to get\r\nthe keys extracted by a model.",
      "properties": {
        "clusters": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "description": "Object mapping ClusterIds to Key lists.",
          "type": "object"
        }
      },
      "type": "object"
    },
    "ModelResult": {
      "description": "Result of a model status query operation.",
      "properties": {
        "createdDateTime": {
          "description": "Get or set the created date time of the model.",
          "format": "date-time",
          "type": "string"
        },
        "lastUpdatedDateTime": {
          "description": "Get or set the model last updated datetime.",
          "format": "date-time",
          "type": "string"
        },
        "modelId": {
          "description": "Get or set model identifier.",
          "format": "uuid",
          "type": "string",
          "x-nullable": false
        },
        "status": {
          "description": "Get or set the status of model.",
          "enum": [
            "created",
            "ready",
            "invalid"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "ModelsResult": {
      "description": "Result of query operation to fetch multiple models.",
      "properties": {
        "models": {
          "description": "Collection of models.",
          "items": {
            "$ref": "#/definitions/ModelResult"
          },
          "type": "array",
          "uniqueItems": false
        }
      },
      "type": "object"
    },
    "TrainRequest": {
      "description": "Contract to initiate a train request.",
      "properties": {
        "source": {
          "description": "Get or set source path.",
          "maxLength": 2048,
          "minLength": 0,
          "type": "string"
        },
        "sourceFilter": {
          "$ref": "#/definitions/TrainSourceFilter",
          "description": "Get or set filter to further search the\r\nsource path for content."
        }
      },
      "required": [
        "source"
      ],
      "type": "object"
    },
    "TrainResult": {
      "description": "Response of the Train API call.",
      "properties": {
        "errors": {
          "description": "Errors returned during the training operation.",
          "items": {
            "$ref": "#/definitions/FormOperationError"
          },
          "type": "array",
          "uniqueItems": false
        },
        "modelId": {
          "description": "Identifier of the model.",
          "format": "uuid",
          "type": "string",
          "x-nullable": false
        },
        "trainingDocuments": {
          "description": "List of documents used to train the model and the\r\ntrain operation error reported by each.",
          "items": {
            "$ref": "#/definitions/FormDocumentReport"
          },
          "type": "array",
          "uniqueItems": false
        }
      },
      "type": "object"
    },
    "TrainSourceFilter": {
      "description": "Filters to be applied when traversing a data source.",
      "properties": {
        "includeSubFolders": {
          "description": "A flag to indicate if sub folders within the set of\r\nprefix folders will also need to be included when searching\r\nfor content to be preprocessed.",
          "type": "boolean"
        },
        "prefix": {
          "description": "A case-sensitive prefix string to filter content\r\nunder the source location. For e.g., when using a Azure Blob\r\nUri use the prefix to restrict subfolders for content.",
          "maxLength": 128,
          "minLength": 0,
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "x-ms-parameterized-host": {
    "hostTemplate": "{Endpoint}/formrecognizer/v1.0-preview",
    "parameters": [
      {
        "$ref": "#/parameters/Endpoint"
      }
    ],
    "useSchemePrefix": false
  }
}