> For the complete documentation index, see [llms.txt](https://docs.mindee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mindee.com/integrations/api-reference/ocr-models.md).
# OCR Models
## Send a file for an ocr utility inference.
> Send a file to the asynchronous processing queue for an ocr utility inference.\
> \
> Results can be retrieved in two ways:\
> \* Loop on the \`polling\_url\` endpoint in the response until the status\
> is \`Processed\` or \`Failed\` (polling).\
> \* Use a webhook to be notified when the inference is finished.\
> Webhooks can be configured on the platform on a per-model basis.\
> \
> Inferences taking longer than 590 seconds will time out.
```json
{"openapi":"3.1.0","info":{"title":"Mindee API","version":"2.0.0"},"servers":[{"url":"https://api-v2.mindee.net"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"JobResponse":{"properties":{"job":{"$ref":"#/components/schemas/Job"}},"type":"object","required":["job"],"title":"JobResponse","description":"Response for a Job."},"Job":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"UUID of the Job."},"model_id":{"type":"string","format":"uuid4","title":"Model Id","description":"UUID of the model to be used for the inference."},"filename":{"type":"string","title":"Filename","description":"Name of the file sent."},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias","description":"Optional alias sent for the file."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Date and time of the Job creation."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"Date and time of the Job completion. Filled once processing is finished."},"status":{"$ref":"#/components/schemas/Status"},"polling_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Polling Url","description":"URL to poll for the Job status."},"result_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Result Url","description":"URL to retrieve the inference results. Will be filled once the inference is ready."},"webhooks":{"items":{"$ref":"#/components/schemas/WebhookResponse"},"type":"array","title":"Webhooks","description":"List of responses from webhooks called. Empty until processing is finished.","default":[]},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"null"}],"description":"If an error occurred during processing, contains the problem details."}},"type":"object","required":["id","model_id","filename","created_at","status","polling_url"],"title":"Job","description":"Information on the processing of a file sent to the Mindee API."},"Status":{"type":"string","enum":["Processing","Failed","Processed"],"title":"Status","description":"Possible states of an operation."},"WebhookResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"UUID of the webhook endpoint."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Date and time the webhook was called."},"status":{"$ref":"#/components/schemas/ExtendedStatus","default":"Processing"},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"null"}],"description":"If an error occurred when calling the webhook, contains the problem details."},"attempts_count":{"type":"integer","title":"Attempts Count","description":"Number of attempts made to call the webhook.","default":0}},"type":"object","required":["id"],"title":"WebhookResponse","description":"Response from a webhook call."},"ExtendedStatus":{"type":"string","enum":["Processing","Failed","Processed","Skipped"],"title":"ExtendedStatus","description":"Possible states of an extended operation."},"ErrorResponse":{"properties":{"status":{"type":"integer","maximum":599,"minimum":100,"title":"Status","description":"The HTTP status code returned by the server."},"detail":{"type":"string","title":"Detail","description":"A human-readable explanation specific to the occurrence of the problem."},"title":{"type":"string","title":"Title","description":"A short, human-readable summary of the problem."},"code":{"type":"string","title":"Code","description":"A machine-readable code specific to the occurrence of the problem."},"errors":{"items":{"$ref":"#/components/schemas/ErrorItem"},"type":"array","title":"Errors","description":"A list of explicit details on the problem.","default":[]}},"type":"object","required":["status","detail","title","code"],"title":"ErrorResponse","description":"Error response detailing a problem. The format adheres to RFC 9457."},"ErrorItem":{"properties":{"pointer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pointer","description":"A JSON Pointer to the location of the body property."},"detail":{"type":"string","title":"Detail","description":"Explicit information on the issue."}},"type":"object","required":["pointer","detail"],"title":"ErrorItem","description":"Explicit details on a problem."}}},"paths":{"/v2/products/ocr/enqueue":{"post":{"tags":["OCR Product"],"summary":"Send a file for an ocr utility inference.","description":"Send a file to the asynchronous processing queue for an ocr utility inference.\n\nResults can be retrieved in two ways:\n* Loop on the `polling_url` endpoint in the response until the status\n is `Processed` or `Failed` (polling).\n* Use a webhook to be notified when the inference is finished.\n Webhooks can be configured on the platform on a per-model basis.\n\nInferences taking longer than 590 seconds will time out.","operationId":"Enqueue_OCR_Product_Inference_v2_products_ocr_enqueue_post","responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"422":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Get the status of a file's processing.
> Get the status of an inference that was previously enqueued.\
> \
> If you are using webhooks there is no need to call this route.\
> \
> When the job \`status\` is \`Processing\` or \`Failed\` the return code will be HTTP 200.\
> \
> When the job \`status\` is \`Processed\` the return code will be HTTP 302.\
> \
> The processing result can then be retrieved in two ways:\
> \* \*\*Recommended:\*\* Using a GET on the URL specified in the \`result\_url\` field of the response\
> \* Allowing your client to redirect on the \`Location\` header of the response\
> \
> Note: set the \`redirect\` parameter to \`false\` to disable the redirection behavior, and always return HTTP 200.
```json
{"openapi":"3.1.0","info":{"title":"Mindee API","version":"2.0.0"},"servers":[{"url":"https://api-v2.mindee.net"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"JobResponse":{"properties":{"job":{"$ref":"#/components/schemas/Job"}},"type":"object","required":["job"],"title":"JobResponse","description":"Response for a Job."},"Job":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"UUID of the Job."},"model_id":{"type":"string","format":"uuid4","title":"Model Id","description":"UUID of the model to be used for the inference."},"filename":{"type":"string","title":"Filename","description":"Name of the file sent."},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias","description":"Optional alias sent for the file."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Date and time of the Job creation."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"Date and time of the Job completion. Filled once processing is finished."},"status":{"$ref":"#/components/schemas/Status"},"polling_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Polling Url","description":"URL to poll for the Job status."},"result_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Result Url","description":"URL to retrieve the inference results. Will be filled once the inference is ready."},"webhooks":{"items":{"$ref":"#/components/schemas/WebhookResponse"},"type":"array","title":"Webhooks","description":"List of responses from webhooks called. Empty until processing is finished.","default":[]},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"null"}],"description":"If an error occurred during processing, contains the problem details."}},"type":"object","required":["id","model_id","filename","created_at","status","polling_url"],"title":"Job","description":"Information on the processing of a file sent to the Mindee API."},"Status":{"type":"string","enum":["Processing","Failed","Processed"],"title":"Status","description":"Possible states of an operation."},"WebhookResponse":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"UUID of the webhook endpoint."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Date and time the webhook was called."},"status":{"$ref":"#/components/schemas/ExtendedStatus","default":"Processing"},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"null"}],"description":"If an error occurred when calling the webhook, contains the problem details."},"attempts_count":{"type":"integer","title":"Attempts Count","description":"Number of attempts made to call the webhook.","default":0}},"type":"object","required":["id"],"title":"WebhookResponse","description":"Response from a webhook call."},"ExtendedStatus":{"type":"string","enum":["Processing","Failed","Processed","Skipped"],"title":"ExtendedStatus","description":"Possible states of an extended operation."},"ErrorResponse":{"properties":{"status":{"type":"integer","maximum":599,"minimum":100,"title":"Status","description":"The HTTP status code returned by the server."},"detail":{"type":"string","title":"Detail","description":"A human-readable explanation specific to the occurrence of the problem."},"title":{"type":"string","title":"Title","description":"A short, human-readable summary of the problem."},"code":{"type":"string","title":"Code","description":"A machine-readable code specific to the occurrence of the problem."},"errors":{"items":{"$ref":"#/components/schemas/ErrorItem"},"type":"array","title":"Errors","description":"A list of explicit details on the problem.","default":[]}},"type":"object","required":["status","detail","title","code"],"title":"ErrorResponse","description":"Error response detailing a problem. The format adheres to RFC 9457."},"ErrorItem":{"properties":{"pointer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pointer","description":"A JSON Pointer to the location of the body property."},"detail":{"type":"string","title":"Detail","description":"Explicit information on the issue."}},"type":"object","required":["pointer","detail"],"title":"ErrorItem","description":"Explicit details on a problem."}}},"paths":{"/v2/jobs/{job_id}":{"get":{"tags":["Polling"],"summary":"Get the status of a file's processing.","description":"Get the status of an inference that was previously enqueued.\n\nIf you are using webhooks there is no need to call this route.\n\nWhen the job `status` is `Processing` or `Failed` the return code will be HTTP 200.\n\nWhen the job `status` is `Processed` the return code will be HTTP 302.\n\nThe processing result can then be retrieved in two ways:\n* **Recommended:** Using a GET on the URL specified in the `result_url` field of the response\n* Allowing your client to redirect on the `Location` header of the response\n\nNote: set the `redirect` parameter to `false` to disable the redirection behavior, and always return HTTP 200.","operationId":"Get_Job_Status_v2_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid4","title":"Job ID","description":"UUID of the job to retrieve"},"description":"UUID of the job to retrieve"},{"name":"redirect","in":"query","required":false,"schema":{"type":"boolean","description":"Automatically redirect to the result URL","default":true,"title":"Redirect"},"description":"Automatically redirect to the result URL"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"302":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}},"description":"Found"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unprocessable Content"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too Many Requests"}}}}}}
```
## Get the result of a completed ocr product inference.
> Get the result of an ocr utility inference that was previously enqueued.\
> \
> Important: always prefer using the value returned in \`job.result\_url\`, rather than calling this endpoint directly.\
> \
> The inference will only be available after it has finished processing.\
> \
> If you are using webhooks there is no need to call this route.\
\
> However, the JSON payload described here is what will be sent to each specified webhook's URL.\
> \
> If you activated the "Delete extracted data when fetched" option for the model,\
> the inference will be deleted after this route completes.\
\
> Any further requests to the same inference ID will return a 404.
```json
{"openapi":"3.1.0","info":{"title":"Mindee API","version":"2.0.0"},"servers":[{"url":"https://api-v2.mindee.net"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"OCRResponse":{"properties":{"inference":{"$ref":"#/components/schemas/OCRInference"}},"type":"object","required":["inference"],"title":"OCRResponse","description":"Response for an ocr utility inference."},"OCRInference":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"UUID of the Inference."},"job":{"$ref":"#/components/schemas/BaseJob","title":"Job","description":"Job the inference belongs to."},"model":{"$ref":"#/components/schemas/InferenceModel"},"file":{"$ref":"#/components/schemas/InferenceFile"},"result":{"$ref":"#/components/schemas/OCRResult"}},"type":"object","required":["id","job","model","file","result"],"title":"OCRInference","description":"The inference result for a ocr utility request."},"BaseJob":{"properties":{"id":{"type":"string","format":"uuid4","title":"Id","description":"UUID of the Job."}},"type":"object","required":["id"],"title":"BaseJob","description":"Base class for Job."},"InferenceModel":{"properties":{"id":{"type":"string","format":"uuid4","title":"ID","description":"UUID of the model."}},"type":"object","required":["id"],"title":"InferenceModel","description":"Model used for the inference."},"InferenceFile":{"properties":{"name":{"type":"string","title":"Name","description":"File name as sent to the API."},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alias","description":"Alias sent to the API."},"page_count":{"type":"integer","minimum":1,"title":"Page Count","description":"Number of pages in the file."},"mime_type":{"type":"string","title":"MIME Type","description":"Detected MIME type of the file."}},"type":"object","required":["name","page_count","mime_type"],"title":"InferenceFile","description":"File used for the inference."},"OCRResult":{"properties":{"pages":{"items":{"$ref":"#/components/schemas/PageOCR"},"type":"array","title":"pages","description":"List of OCR results for each page in the document."}},"type":"object","required":["pages"],"title":"OCRResult","description":"Result of the OCR utility inference."},"PageOCR":{"properties":{"words":{"items":{"$ref":"#/components/schemas/WordOCR"},"type":"array","title":"Words","description":"List of words extracted from the document page."},"content":{"type":"string","title":"Content","description":"Full text content extracted from the document page."}},"type":"object","required":["words","content"],"title":"PageOCR","description":"OCR result for a single page."},"WordOCR":{"properties":{"content":{"type":"string","title":"Content","description":"Text content of the word."},"polygon":{"items":{"prefixItems":[{"type":"number","maximum":1,"minimum":0,"title":"Coordinate","description":"Coordinate value relative to document edge."},{"type":"number","maximum":1,"minimum":0,"title":"Coordinate","description":"Coordinate value relative to document edge."}],"type":"array","maxItems":2,"minItems":2,"title":"Point","description":"Relative coordinates of a point in [X,Y] notation."},"type":"array","minItems":3,"title":"Polygon","description":"Position information as a list of points in clockwise order."}},"type":"object","required":["content","polygon"],"title":"WordOCR","description":"OCR result for a single word extracted from the document page."},"ErrorResponse":{"properties":{"status":{"type":"integer","maximum":599,"minimum":100,"title":"Status","description":"The HTTP status code returned by the server."},"detail":{"type":"string","title":"Detail","description":"A human-readable explanation specific to the occurrence of the problem."},"title":{"type":"string","title":"Title","description":"A short, human-readable summary of the problem."},"code":{"type":"string","title":"Code","description":"A machine-readable code specific to the occurrence of the problem."},"errors":{"items":{"$ref":"#/components/schemas/ErrorItem"},"type":"array","title":"Errors","description":"A list of explicit details on the problem.","default":[]}},"type":"object","required":["status","detail","title","code"],"title":"ErrorResponse","description":"Error response detailing a problem. The format adheres to RFC 9457."},"ErrorItem":{"properties":{"pointer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pointer","description":"A JSON Pointer to the location of the body property."},"detail":{"type":"string","title":"Detail","description":"Explicit information on the issue."}},"type":"object","required":["pointer","detail"],"title":"ErrorItem","description":"Explicit details on a problem."}}},"paths":{"/v2/products/ocr/results/{inference_id}":{"get":{"tags":["OCR Product"],"summary":"Get the result of a completed ocr product inference.","description":"Get the result of an ocr utility inference that was previously enqueued.\n\nImportant: always prefer using the value returned in `job.result_url`, rather than calling this endpoint directly.\n\nThe inference will only be available after it has finished processing.\n\nIf you are using webhooks there is no need to call this route.
\nHowever, the JSON payload described here is what will be sent to each specified webhook's URL.\n\nIf you activated the \"Delete extracted data when fetched\" option for the model,\nthe inference will be deleted after this route completes.
\nAny further requests to the same inference ID will return a 404.","operationId":"Get_OCR_Product_Result_v2_products_ocr_results__inference_id__get","parameters":[{"name":"inference_id","in":"path","required":true,"schema":{"type":"string","format":"uuid4","title":"Inference ID","description":"UUID of the inference to retrieve"},"description":"UUID of the inference to retrieve"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OCRResponse"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unprocessable Content"}},"requestBody":{"content":{"multipart/form-data":{"schema":{"description":"Form to enqueue an inference for utility models.","properties":{"model_id":{"description":"Model ID to use for the inference.","format":"uuid4","title":"Model Id","type":"string"},"file":{"anyOf":[{"contentMediaType":"application/octet-stream","type":"string"},{"type":"null"}],"description":"Upload a file as bytes. Required if `url` is not provided.","title":"File"},"url":{"anyOf":[{"format":"uri","maxLength":2048,"minLength":1,"type":"string"},{"type":"null"}],"description":"Download the file from a URL, must be secure (HTTPS) and publicly available. Required if `file` is not provided.","title":"Url"},"file_base64":{"anyOf":[{"minLength":15,"type":"string"},{"type":"null"}],"description":"Upload a file as a base 64 string. Used as an alternative to `file`. *Not recommended*, for specific use only.","title":"File Base64"},"webhook_ids":{"description":"Webhook IDs to call after all processing is finished. If empty, no webhooks will be used. Can be a list or comma-separated string.","items":{"format":"uuid4","type":"string"},"title":"Webhook Ids","type":"array"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional filename to associate with the uploaded or fetched file.","title":"Filename"},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional: a free-form string to tag the request with your own identifier. For example, an internal document ID, reference number, or database key. If set, it will be included in the job and result responses.","title":"Alias"}},"required":["model_id"],"title":"UtilityEnqueueForm","type":"object"}},"application/json":{"schema":{"description":"Form to enqueue an inference for utility models.","properties":{"model_id":{"description":"Model ID to use for the inference.","format":"uuid4","title":"Model Id","type":"string"},"url":{"anyOf":[{"format":"uri","maxLength":2048,"minLength":1,"type":"string"},{"type":"null"}],"description":"Download the file from a URL, must be secure (HTTPS) and publicly available. Required if `file` is not provided.","title":"Url"},"file_base64":{"anyOf":[{"minLength":15,"type":"string"},{"type":"null"}],"description":"Upload a file as a base 64 string. Used as an alternative to `file`. *Not recommended*, for specific use only.","title":"File Base64"},"webhook_ids":{"description":"Webhook IDs to call after all processing is finished. If empty, no webhooks will be used. Can be a list or comma-separated string.","items":{"format":"uuid4","type":"string"},"title":"Webhook Ids","type":"array"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional filename to associate with the uploaded or fetched file.","title":"Filename"},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional: a free-form string to tag the request with your own identifier. For example, an internal document ID, reference number, or database key. If set, it will be included in the job and result responses.","title":"Alias"}},"required":["model_id"],"title":"UtilityEnqueueForm","type":"object"}}},"required":true}}}}}
```
{% openapi-webhook spec="mindee-api" name="ocr-utility-processed" method="post" %}
[mindee-api](https://api-v2.mindee.net/openapi.json)
{% endopenapi-webhook %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.mindee.com/integrations/api-reference/ocr-models.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.