Perform an analysis

Perform an AI analysis on specific inputs.

To perform an analysis, an input and its context (ie. the name of the task group being analyzed) must be provided as inputs. The goal of the analysis is to return values computed by computer vision models on the tasks belonging to the task group analyzed. The context value is the name of the task group.

Two types of inputs are currently supported : images and PDF files.

• Images can either be sent in Base64 or through URLs that give us access to the images. URLs can be public, signed or private URLs with IP whitelisting. The following prefix must be added to analyze Base64 images: data:image/jpg;base64,{your_base64_image}

• PDF files can either be sent in Base64 or through URLs that give us access to the images. The following prefix must be added to analyze Base64 PDFs: data:application/pdf;base64,{your_base64_pdf}

Only one image can be analyzed per analysis and image size is limited to 5MB.

PDF size is limited to 8MB.

Depending on your configuration of the Deepomatic application, there may be two levels of analysis.

The first level (data conformity) validates the conformity of the inputs provided, particularly the photo. The second level (job conformity), which is only triggered if the first-level checks have been validated, corresponds to the more advanced analysis of the image with specific business rules.

All endpoints are described with the EU (Europe) server format. If your application runs on the US server, you will need to use the following format: https://api.{site-id}.customers.us1.deepomatic.com/v0.2/.

Every Deepomatic application is versioned. We recommend to not integrate any logic based on the tasks and task groups ids as those ids changes when a version is upgraded. You can instead use tasks and task groups names that are agnostic to version changes.

Analyze inputs

POST https://api.{site-id}.customers.deepomatic.com/v0.2/work-orders/{id}/analyze/

Path Parameters

Name	Type	Description
id*	string	Id of the work order to send the inputs to. This id corresponds to the id returned in the create a work order API response.

Headers

Name	Type	Description
Authorization*	string	Deepomatic API Key associated to your account.
Accept-Language	string	Language of the data conformity error message. Language supported include English ("en"), French ("fr"), German ("de") and Spanish ("es").

Request Body

Name	Type	Description
inputs*	array	List of inputs The inputs depend on the logic of the Deepomatic application. Contact our team for more information on the inputs needed for your specific application. See below for more information on the format of the inputs to be transmitted.

200: OK Everything worked as expected: a response containing the analysis information is returned.

Response format

inputs - array : array containing the different inputs sent to perform the analysis including the conformity_messages associated in case a data conformity check is not passed.

conformity_messages - array : array returned when a data conformity check is not passed. It contains information such as the code , the name and the message associated to the check. The check level is also provided and two values can be returned: "warning" and "error". Depending on the level set in our platform, different responses will be returned (for more details on the responses' format, see below).

state - object : object containing in particular the task analyzed_value which is dependent on the task type (eg. if the type is "Boolean", then the value returned will be either True or False), the message associated to the analysis and the analyzed_inputs array that allows you to retrieve the bounding boxes detected.

It is recommended to display those 3 different informations (analyzed_value, message, and analyzed_inputs) to the field workers to help them better understand AI results.

Only tasks impacted by the analysis are returned in the responses.

Below an example of response when no data conformity warning or error has been raised:

{
    "id": "5f3a41ed-1add-48c7-b89a-7346c99a0b56",
    "analysis_date": "2023-05-29T17:43:12.260474Z",
    "inputs": [
        {
            "id": "dd38664f-8d48-4fcb-bf52-3e940b55b0d3",
            "name": "context",
            "metadata": {}
        },
        {
            "id": "f5c76f7d-79ad-424f-bca6-5117c48efd9b",
            "name": "image_input",
            "conformity_messages": []
        }
    ],
    "tasks": [
        {
            "id": "db081122-b571-48d9-b19b-6f690be1e94e",
            "name": "equipment_after_intervention",
            "label": "Is it a photo of the equipment after intervention?",
            "type": "Boolean",
            "group_id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
            "group_name": "equipment-after-intervention",
            "state": {
                "id": "2052385d-ac0c-4080-b8e9-fa4814b5b407",
                "analyzed_value": true,
                "analyzed_date": "2023-05-29T17:43:12.260474Z",
                "corrected_value": null,
                "corrected_date": null,
                "message": "Valid photo",
                "is_conformity_validated": true,
                "analyzed_inputs": [
                    {
                        "input_id": "f5c76f7d-79ad-424f-bca6-5117c48efd9b",
                        "regions": []
                    }
                ]
            }
        },
        {
            "id": "b5293ca9-faa1-4880-8c07-1bb0475da4d6",
            "name": "equipment_after_intervention_degradations",
            "label": "Number of degradations",
            "type": "Number",
            "group_id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
            "group_name": "equipment-after-intervention",
            "state": {
                "id": "54ef3d77-026c-4a5b-9eee-971ceb00b942",
                "analyzed_value": 2.0,
                "analyzed_date": "2023-05-29T17:43:12.260474Z",
                "corrected_value": null,
                "corrected_date": null,
                "message": "Degradations have been spotted on the equipment",
                "is_conformity_validated": false,
                "analyzed_inputs": [
                    {
                        "input_id": "f5c76f7d-79ad-424f-bca6-5117c48efd9b",
                        "regions": [
                            {
                                "bbox": {
                                    "xmax": 0.23577146,
                                    "xmin": 0.21882737,
                                    "ymax": 0.6945216,
                                    "ymin": 0.6803977
                                },
                                "score": 0.9281037449836731,
                                "concept": "degradations"
                            },
                            {
                                "bbox": {
                                    "xmax": 0.2890531,
                                    "xmin": 0.27096856,
                                    "ymax": 0.68964636,
                                    "ymin": 0.67994857
                                },
                                "score": 0.9210498332977295,
                                "concept": "degradations"
                            }
                        ]
                    }
                ]
            }
        }
    ],
    "task_groups": [
        {
            "id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
            "name": "equipment-after-intervention",
            "display_name": "Equipment after intervention",
            "order": 0, 
            "engage_app_version_id": "fb5516ed-355e-4b2c-9d11-6c39b660045f"
        }
    ]
}

If only a warning or several warnings are triggered, the response will contain the conformity messages and the analysis on the tasks and task groups. Below an example of response with a Duplicate warning triggered:

{
    "id": "4ffd02df-c4a5-4db8-9c2b-aca742c8283b",
    "analysis_date": "2023-05-29T17:44:51.260474Z",
    "inputs": [
        {
            "id": "f8a904cd-90b1-4fe7-aeff-8d0b6c92d564",
            "name": "context",
            "metadata": {}
        },
        {
            "name": "image_input",
            "id": "965a5f54-7ace-4e8e-af5b-74f816d3df5f",
            "conformity_messages": [
             {
                "code": 1,
                "name": "Duplicate",
                "level": "warning",
                "source": "DataConformity",
                "message": "This photo has already been integrated. Please take a new photo."
             }
        }
    ],
    "tasks": [
        {
            "id": "db081122-b571-48d9-b19b-6f690be1e94e",
            "name": "equipment_after_intervention",
            "label": "Is it a photo of the equipment after intervention?",
            "type": "Boolean",
            "group_id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
            "group_name": "equipment-after-intervention",
            "state": {
                "id": "2052385d-ac0c-4080-b8e9-fa4814b5b407",
                "analyzed_value": true,
                "analyzed_date": "2023-05-29T17:44:51.260474Z",
                "corrected_value": null,
                "corrected_date": null,
                "message": "Valid photo",
                "is_conformity_validated": true,
                "analyzed_inputs": [
                    {
                        "input_id": "965a5f54-7ace-4e8e-af5b-74f816d3df5f",
                        "regions": []
                    }
                ]
            }
        },
        {
            "id": "b5293ca9-faa1-4880-8c07-1bb0475da4d6",
            "name": "equipment_after_intervention_degradations",
            "label": "Number of degradations",
            "type": "Number",
            "group_id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
            "group_name": "equipment-after-intervention",
            "state": {
                "id": "5658cfc5-1d02-478a-a041-f43eac25b26d",
                "analyzed_value": 2.0,
                "analyzed_date": "2023-05-29T17:44:51.260474Z",
                "corrected_value": null,
                "corrected_date": null,
                "message": "Degradations have been spotted on the equipment",
                "is_conformity_validated": false,
                "analyzed_inputs": [
                    {
                        "input_id": "965a5f54-7ace-4e8e-af5b-74f816d3df5f",
                        "regions": [
                            {
                                "bbox": {
                                    "xmax": 0.23577146,
                                    "xmin": 0.21882737,
                                    "ymax": 0.6945216,
                                    "ymin": 0.6803977
                                },
                                "score": 0.9281037449836731,
                                "concept": "degradations"
                            },
                            {
                                "bbox": {
                                    "xmax": 0.2890531,
                                    "xmin": 0.27096856,
                                    "ymax": 0.68964636,
                                    "ymin": 0.67994857
                                },
                                "score": 0.9210498332977295,
                                "concept": "degradations"
                            }
                        ]
                    }
                ]
            }
        }
    ],
    "task_groups": [
        {
            "id": "6f15b52e-4717-4ec5-a8b2-bd58e7eec5ca",
            "name": "equipment-after-intervention",
            "display_name": "Equipment after intervention",
            "order": 0, 
            "engage_app_version_id": "fb5516ed-355e-4b2c-9d11-6c39b660045f"
        }
    ]
}

If an error, several errors or both errors and warnings are triggered, then the response will contain the conformity messages and empty fields for tasks and task groups. In these cases the second-level analysis is therefore not provided.

Below an example of response with a Duplicate error triggered:

{
    "id": "fdebc265-23b8-4172-a19a-0994b8b8cf7b",
    "analysis_date": "2023-05-29T17:45:43.260474Z",
    "inputs": [
        {
            "id": "a6d87e3b-8b22-4c9f-bfd3-61c94c7a1f7d",
            "name": "context",
            "metadata": {}
        },
        {
            "name": "image_input",
            "id": "c8dedc58-3862-44c7-a1c0-45f9be430421",
            "conformity_messages": [
             {
                "code": 1,
                "name": "Duplicate",
                "level": "error",
                "source": "DataConformity",
                "message": "This photo has already been integrated. Please take a new photo."
             }
        }
    ],
    "tasks": [],
    "task_groups": []
}

400: Bad Request A required field is not specified or wrong.

The returned list contains all the specified inputs in the same order. The input(s) for which problems were identified are specified, along with the reason for the failure.

{"inputs": [{"data": ["Field 'type' is missing. This field is required."]}, {}, {}, {}]}
OR
{"inputs": [{}, {"data": ["Failed to download image https://storage.googleapis.com/dp-vulcan/tests/imgs/dog.jpgWRONG"]}, {}, {}]}

403: Forbidden The API key doesn't have permissions to perform the request.

{"detail": "Authentication credentials not provided."}
OR
{"detail": "No user found for such apiKey."}

404: Not Found The requested resource (work order id) doesn't exist.

{"detail": "WorkOrder not found!"}

500: Internal Server Error WorkflowServerExecutionError

Request example for an image input (URL)

curl 'https://api.{site-id}.customers.deepomatic.com/v0.2/work-orders/{id}/analyze/' \    
    -X POST \
    -H 'Authorization: Token <your_api_key>' \       
    -H 'Content-Type: application/json' \       
    -d'{
        "inputs":[
            {
                "name": "image_input", 
                "data": {
                    "type": "image", 
                    "value": "image-url"
                    }
            }, 
            {
                "name": "context", 
                "data": {"type": "text", "value": "equipment-after-intervention"}
            }
        ]
}'

Request example for an image input (Base64)

curl 'https://api.{site-id}.customers.deepomatic.com/v0.2/work-orders/{id}/analyze/' \    
    -X POST \
    -H 'Authorization: Token <your_api_key>' \       
    -H 'Content-Type: application/json' \       
    -d'{
        "inputs":[
            {
                "name": "image_input", 
                "data": {
                    "type": "image", 
                    "value": "data:image/jpg;base64, base64_image"
                    }
            }, 
            {
                "name": "context", 
                "data": {"type": "text", "value": "equipment-after-intervention"}
            }
        ]
}'

Request example for a PDF input (URL)

curl 'https://api.{site-id}.customers.deepomatic.com/v0.2/work-orders/{id}/analyze/' \    
    -X POST \
    -H 'Authorization: Token <your_api_key>' \       
    -H 'Content-Type: application/json' \       
    -d'{
        "inputs":[
            {
                "name": "file_input", 
                "data": {
                    "type": "pdf", 
                    "value": "pdf-url"
                    }
            }, 
            {
                "name": "context", 
                "data": {"type": "text", "value": "pdf-example"}
            }
        ]
}'

Request example for a PDF input (Base64)

curl 'https://api.{site-id}.customers.deepomatic.com/v0.2/work-orders/{id}/analyze/' \    
    -X POST \
    -H 'Authorization: Token <your_api_key>' \       
    -H 'Content-Type: application/json' \       
    -d'{
        "inputs":[
            {
                "name": "file_input", 
                "data": {
                    "type": "pdf", 
                    "value": "data:application/pdf;base64, base64_pdf"
                    }
            }, 
            {
                "name": "context", 
                "data": {"type": "text", "value": "pdf-example"}
            }
        ]
}'