PIX4Dinspect API Documentation

Download OpenAPI specification:Download

Authentication

OAuth2

Pix4Dinspect API authentication procedure

This document describes how to get started with the Pix4D Inspect REST API, which provides third party applications access to the Pix4Dinspect API service. It allows a Pix4D Inspect client to access his/her data on the cloud and perform a range of operations on them.

  • For end to end security, HTTPS is used in all the APIs
  • The base URL for API endpoints is: https://api.inspect.pix4d.com
  • Each REST API call needs to be authenticated. See Authentication below
  • The communication format is expected to be JSON, unless otherwise stated

Getting access to Pix4Dinspect REST API

To register the application and start using the REST API you will need to acquire a Pix4Dinspect license. Please contact us at Salesteam (at) pix4d.com and we'll help you get set up and will give you an api key that represent your application, the one that will connect to the Pix4DinspectAPI and that you will use to authenticate to the API.

Note that the api key as an identifier for the client application should be handled securely.

API Authentication

Equipped with the Inspect api key, the first step is to retrieve an authentication jwt token. An authentication token identifies both the application connecting to the API and the Inspect user this application is connecting on behalf of.

The jwt token and the api key must be passed along every single request that the application makes to the Pix4D Inspect API. They are passed in the HTTP Authorization header, like so:

Authorization: Bearer <INSPECT_JWT_TOKEN>
X-Api-Key: <API_KEY>

Working under an organization

If you are working on behalf of an organization, there is an extra step needed. Pick your organization UUID (it is included in the url when accessing the organization managing page) and add it among the previously required headers:

pix4d-organization-uuid: <ORGANIZATION_UUID>

Client Credentials flow

Using this flow, an API client application can get access to its own Inspect user account (and only to that account). With this method, the authentication is straightforward and only requires the applications' user/password pair.

The client must send the following HTTP POST request to https://api.inspect.pix4d.com/v1/auth/token/ with a payload containing:

  • username: the email account of the account
  • password: the password of the account

And a header containing:

  • x-api-key: the api-key that identifies the account

example:

curl --request POST "https://api.inspect.pix4d.com/v1/auth/token/" \ 
  --header "Content-Type: application/json" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --data-raw "{
      \"username\": \"company@pix4d.com\",
      \"password\": \"sddfr321\"
  }"

Token information

Token content

The response you receive when performing the authentication request above has the following content (In JSON):

  • api_token: the token value that you will have to join in all your requests
  • expires_in: the number of seconds the token is valid for. After this number of seconds, API requests using this token will get rejected and you will need to request a new token through the authentication procedure again
{
  "api_token": "<ACCESS_TOKEN>",
  "expires_in": 36000
}

Refreshing the token

When the token expires, you simply need to perform the above authentication procedure again to get a fresh token.

Using the API

For an in-depth description of all possible API commands, please refer to the API documentation. This documentation is only available for users who already have an API access.

Security Scheme Type OAuth2
Client Credentials OAuth Flow
Scopes:
  • cloud:read -

    Grant read access

  • cloud:write -

    Grant write access

First Example

In this guide, you will discover how to get a token, upload a new inspection, get it processed, and access the results.

This same tutorial is available here as a Jupyter notebook, for the users that prefer to follow a Python implementation.

IMPORTANT: To follow this tutorial it is necessary to have at least one resource of the type Projects in the account and one of the type Tower inventory if you select the detect_antennas option for the processing. To know more about allowance please read the allowance guide.

Prerequisites

API Access

You need a Pix4Dinspect license to authenticate and get an access to the API. Please contact your Pix4D reseller to start a trial if you don't have a license already. More information is available on Pix4D Inspect on our product page.

With this license comes your authentication information, your username, password and api-key which are the values you need in this guide.

Terminal tooling

This guide can be completed from the Terminal, using basic tooling:

  • curl command line is used to call the API, it should be included in your OS or docker image.
  • aws-cli is used to upload and download the data, you can get it directly from AWS: https://aws.amazon.com/cli/

Photos to process

We will use a set of photos to be processed in this guide. If you don't have a good dataset at your disposal, feel free to download one of our sample datasets, for example the demo dataset. We consider your are unzipping the archive in ./photos in this guide.

Authenticate

We are using OAuth2 Client Credientials flow to generate an api token. Using the Username, Password and Api-Key provided with your Pix4Dinspect license, you can get an Api Token using the following curl command:

export INSPECT_USERNAME=__YOUR_USERNAME__
export INSPECT_PASSWORD=__YOUR_PASSWORD__
export INSPECT_API_KEY=__YOUR_API_KEY__
curl --request POST "https://api.inspect.pix4d.com/v1/auth/token/" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --data-raw "{
      \"username\": \"${INSPECT_USERNAME}\",
      \"password\": \"${INSPECT_PASSWORD}\"
  }"

The response body is a JSON document containing an api_token attribute:

{
  "api_token": "<INSPECT_JWT_TOKEN>",
  "expires_in": 172800,
}

For the following example we will reference the token as INSPECT_JWT_TOKEN

export INSPECT_JWT_TOKEN=__INSPECT_JWT_TOKEN__

You can learn more about authentication in the reference documentation (see Authentication).

Create a new asset

Let's start by creating an asset. The only required parameters are the asset name and the asset type, the rest are optional. The list of available asset types and their ids are included in the reference documentation (see Asset creation).

All of the parameters can be passed as a JSON payload in the request body.

curl --request POST "https://api.inspect.pix4d.com/v1/assets/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --data-raw "{\"name\": \"Demo Cell Tower\", \"type\": 1}"

Create your first inspection

Once having an asset, it's possible to create an inspection. To do this, we only need as mandatory fields the id of the asset created before and the processing parameters choosen for the inspection. The additional fields you can include in the inspection are included in the reference documentation (see Inspection creation).

As in the previous step, the parameters can be passed as a JSON payload in the request body.

Since this json can be too long, you can store it in a json file inside your working directory as inspection.json and reference it later with curl.

    {
      "asset": 0,
      "processing_parameters": {
        "is_video": false,
        "generate_point_cloud": true,
        "clip_point_cloud": true,
        "clipping_radius": 0,
        "detect_antennas": true
      }
    }
curl --request POST "https://api.inspect.pix4d.com/v1/inspections" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --data @inspection.json

The response will be a 201 CREATED and the response body will include the inspection details. It can be usefull to add the inspection id as an enviroment variable during this tutorial.

export INSPECTION_ID=<THE INSPECTION ID>

Upload the photos

It is recommended to use the shell AWS CLI or the python boto3 library but other tools can work as well. First, we need to retrieve the AWS S3 credentials associated with this inspection:

curl --url https://api.inspect.pix4d.com/v1/inspections/$INSPECTION_ID/s3_credentials/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

The answer contains all the S3 information we need, at least the access_key, secret_key and the session_token.

{
  "access_key": "ASIATOCJLBKSU2CVJIHR",
  "secret_key": "5OGGBSvn8Sesdu8l...<remainder of the secret key>",
  "session_token": "FwoGZXIvYX...<remainder of security token>",
  "expiration": "2021-05-10T21:55:47Z",
  "bucket": "prod-pix4d-cloud-default",
  "key": "user-199a56ab-7ac6-d6d1-4778-5b4d338fc9de/project-883349",
  "server_time": "2021-05-19T09:55:47.357641+00:00",
  "region": "us-east-1"
}

We can store the S3 credentials in our environment, so that they will get picked up by the AWS CLI tool.

export AWS_ACCESS_KEY_ID=ASIATOCJLBKSU2CVJIHR
export AWS_SECRET_ACCESS_KEY='5OGGBSvn8Sesdu8l...<remainder of the secret key>'
export AWS_SESSION_TOKEN='AQoDYXdzEJr...<remainder of security token>'
export S3_BUCKET=prod-pix4d-cloud-default
export S3_BASE_PATH='user-199a56ab-7ac6-d6d1-4778-5b4d338fc9de/project-883349'

Make sure to prefix all your desired destination locations with the path returned in the credentials call. This is the only place for which write access is granted. Make sure that the files are proper images and their names include an extension supported by Pix4Dinspect.

Provided your images are located in a folder located at $HOME/images, and that it contains only images, you can run the command:

aws s3 cp ./photos/ "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive

If your folder contains multiple images, you need to copy them one by one, likely using a script.

aws s3 cp $HOME/images/DJI_0389.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0390.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0391.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0392.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0393.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0394.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive

Then you need to register the images in the Pix4D Inspect API so that they will be processed. It is possible to upload files that are not inspection inputs, and it is not possible to know which files are meant as input. It is therefore required to register each S3 uploaded file in the API. Register the uploaded files you uploaded (single API call for less than 500 images):

curl --request POST --url https://api.inspect.pix4d.com/v1/inspections/$INSPECTION_ID/register_images/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{
      \"image_keys\": [
        \"${S3_BASE_PATH}//DJI_0389.JPG\",
        \"${S3_BASE_PATH}//DJI_0390.JPG\",
        \"${S3_BASE_PATH}//DJI_0391.JPG\",
        \"${S3_BASE_PATH}//DJI_0392.JPG\",
        \"${S3_BASE_PATH}//DJI_0393.JPG\",
        \"${S3_BASE_PATH}//DJI_0394.JPG\"
      ]
    }"

The response should confirm that the various images have been registered amongst other data.

{ "nb_images_registered": 10 }

Start processing

You are now ready to start processing your inspection:

curl --request POST --url https://api.inspect.pix4d.com/v1/inspections/$INSPECTION_ID/process/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

IMPORTANT: The allowance resources will be consumed when starting the processing of an inspection. Not before, not after.

Check the processing state

curl --url https://api.inspect.pix4d.com/v1/inspections/$INSPECTION_ID/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

A response can look like:

{
    "id": 1417,
    "project_id": 745411,
    "can_retry": false,
    "retry_of": null,
    "retries": [],
    "asset": 915,
    "status": 7,
    "pcs_task_uuid": "bcdbf959-be66-4595-bcea-35879d5370d5",
    "inspection_date": "2020-09-17T17:09:43.116225+02:00",
    "annotations": [],
    "description": "Demo inspection",
    "name": "My first inspection",
    "is_main": true,
    "ground_reference_altitude": "12.6383",
    "processing_parameters": null,
    "report_status": "available",
    "created_at": "2020-09-17T17:09:43.116225+02:00",
    "updated_at": "2021-06-15T15:20:39.576966+02:00"
}

Once the status changes to Processing completed (status 7), the inspection's main outputs are ready to be retrieved.

When the inspection is processed, it is possible to access to the visualization page through a browser, using the same credentials as in this tutorial (username and password). The URL should look like this: https://inspect.pix4d.com/project/<project_id>/

You can learn more about how to share your inspections in the reference documentation (see ShareTokens).

Create annotations

With the inspection completed, it is time to create your first annotations. In order to do it, first is needed to have the list of the cameras of the inspection, because each of them contains the photo_id, a unique idenfifier of the image you are going to annotate.

curl --url https://api.inspect.pix4d.com/v1/inspections/$INSPECTION_ID/cameras/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

The list of cameras can look like:

[
    {
        "id": 160647,
        "photo_id": 123456789,
        "filename": "DJI_0002.JPG",
        "location": {
            "latitude": 49.32146480555556,
            "elevation": 80.872,
            "longitude": 2.4840561111111112
        },
        "dimensions": {
            "x": 5472,
            "y": 3648
        },
        "quaternions": [
            0.3277946211241777,
            0.06728657242558705,
            -0.9231025706765603,
            0.18948574496145876
        ],
        "is_master": false,
        "is_reviewed": false,
        "is_visible": true
    }
]

Having the list of the cameras on your hand, you can choose wich image you want to annotate. In this example let's suppose you are creating an annotation for the image DJI_0389.JPG, which appears in the list of the cameras with the photo_id 123456789. To do it, we need to make a request similar to this, that must include the fields inspection, photo_id, data and type as mandatory.

The field data requires special attention since it is intended to store the information needed to draw the annotation. It must contain a JSON object that contains a coords_2d object. coords_2d must contain four points with values between 0 to 1, representing the position of the annotation square in the photo as a percentage, being (0.0, 0.0) the upper left point of the photo and (1.0, 1.0) its bottom right one.

It is possible to calculate the coords_3d field (position of the annotation in the point cloud) adding this flag ?coords_3d=true to the URL.

curl --request POST --url https://api.inspect.pix4d.com/v1/annotations/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key: ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{
    \"inspection\": 1,
    \"photo_id\": 123456789,
    \"type\": \"Damage\",
    \"name\": \"My first annotation\",
    \"data\": {
      \"coords_2d\": [
          [
              0.44901315789473684,
              0.20443564967105254
          ],
          [
              0.44901315789473684,
              0.5358501233552632
          ],
          [
              0.6699561403508772,
              0.5358501233552632
          ],
          [
              0.6699561403508772,
              0.20443564967105254
          ]
        ],
      \"links\": [
          {
            \"link\": \"https://www.pix4d.com/\",
            \"description\": \"Pix4d\"
          }
        ]
      }
    }"

Allowance

Understanding the Allowance

This document describes how to check the allowance available in your account with the Pix4D Inspect REST API. In the following sections it is necessary to have a jwt_token and an api-key, if you don't know how to get them please take a look to reference documentation (see Authentication). Other important requirements are:

  • For end to end security, HTTPS is used in all the APIs
  • The base URL for API endpoints is: https://api.inspect.pix4d.com/v1/
  • Each REST API call needs to be authenticated.
  • The communication format is expected to be JSON, unless otherwise stated

Getting the types of resources available

The Pix4D Inspect allowance is based on different types of resources being the Projects the main one. These resources can be purchased and spent independently, but having in mind the following restrictions:

  • At least one Projects resource has to be spent each time an inspection is processed.
  • It is not possible to spend additional resources (e.g. Tower inventory) once the inspection has been processed.

To get the type of resources available in Pix4D Inspect run:

curl --url https://inspect.pix4d.com/v1/allowance/types/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

Getting the resources available for my account

To get the resources available for your Pix4D Inspect account run:

curl --url https://inspect.pix4d.com/v1/allowance/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

The response will include the number of resources available for each type.

Please contact the Pix4D sales department if you don't have enough resources. More information is available on Pix4D Inspect on our product page.

Getting the history of resources for my account

To get the resources available for your Pix4D Inspect account run:

curl --url https://inspect.pix4d.com/v1/allowance/history/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

This will return a list with the history of all your ingress and egress transactions and their details.

auth

Get an inspect token with the provided credentials

Summary

Most of the Inspect API endpoints require authentication. You need to include a Authorization: Bearer TOKEN in your requests.

To get the token you must send your credentials (username and password) inside the body.

Request Body schema: application/json
username
required
string (Username) non-empty
password
required
string (Password) non-empty

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "api_token": "string",
  • "expires_in": 0
}

allowance

Get allowance balance

Summary

Returns the current balance of the user's organization allowance for every type of allowance.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all allowance records for the user's organization

Summary

Returns detailed information about the user's transactions regarding their usage allowance.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a retry of an Inspection

Summary

Creates a new inspection based on the original one as a retry and refund resources.

If all conditions are met, this will create a new inspection as a retry of the original one, but without using new resources. This will "recycle" the original resources that were used in the original (parent) inspection.

Conditions

In order for an inspection to be marked as a retry, it has to meet the following requirements:

  • The inspection must belong to the user or one of their organizations
  • The inspection must have been created less than 15 days ago
  • The inspection must be in a valid state: [7, 8, 14, 16, 17, 18, 21, 22, 23]
  • The inspection must not have a retry already in progress
  • The inspection must have less than 2 retries

Field description

Field inspection is the ID of the original inspection where the resources were used for.

Field description is optional.

Request Body schema: application/json
inspection
required
integer (Inspection)
object
description
string (Description) Nullable

Responses

Request samples

Content type
application/json
{
  • "inspection": 0,
  • "processing_parameters": {
    },
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "project_id": 0,
  • "project_uuid": "1de37675-f868-4726-bb1d-b08d89f463f9",
  • "app_source": "inspect",
  • "can_retry": true,
  • "retry_of": 0,
  • "retries": [
    ],
  • "asset": 0,
  • "status": 0,
  • "additional_statuses": {
    },
  • "pcs_task_uuid": "b0fd4e5e-bcab-462c-9bf5-906c59a263b6",
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "is_main": true,
  • "base_plate_location": { },
  • "top_point_location": { },
  • "base_plate_size": 0,
  • "processing_parameters": {
    },
  • "processing_backend": "mapper",
  • "report_status": "not available",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get all Allowance Types

Summary

Returns the list of availabe Allowance types.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

annotations

Create a new Annotation

Summary

Creates a new photo Annotation.

Field description

Fields inspection, photo_id and type are mandatory.

The photo_id field is included among the information of each camera.

The field data is also mandatory and must contain a JSON object that contains a coords_2d object. coords_2d must contain four points with values between 0 to 1, representing the position of the annotation square in the photo as a percentage, being (0.0, 0.0) the upper left point of the photo and (1.0, 1.0) its bottom right one.

It is also possible to include inside the data field a links object with related information about the annotation.

Field name is optional.

Field number is automatically generated and is read only.

Field severity_level is optional and must be an integer between 0 and 5.

Field description is optional.

Fields created_at and updated_at are automatically filled by the back-end.

IMPORTANT: It is possible to calculate the coords_3d field (position of the annotation in the point cloud) adding this flag ?coords_3d=true to the URL.

Example.

{
    "inspection": 1,
    "photo_id": 123456789,
    "type": "Damage",
    "name": "My first annotation",
    "data": {
        "coords_2d": [
            [
                0.44901315789473684,
                0.20443564967105254
            ],
            [
                0.44901315789473684,
                0.5358501233552632
            ],
            [
                0.6699561403508772,
                0.5358501233552632
            ],
            [
                0.6699561403508772,
                0.20443564967105254
            ]
        ],
        "links": [
            {
                "link": "https://www.pix4d.com/",
                "description": "Pix4d"
            }
        ]
    }
}
Request Body schema: application/json
type
required
string (Type) [ 1 .. 255 ] characters
inspection
required
integer (Inspection)
name
string (Name) [ 1 .. 255 ] characters Nullable
data
required
object (Data)
severity_level
integer (Severity level)
Default: 0
description
string (Description) Nullable
photo_id
required
integer (Photo id) [ 0 .. 2147483647 ]
coords_3d
object (Coords 3d) Nullable
public
boolean (Public)

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "inspection": 0,
  • "name": "string",
  • "data": { },
  • "severity_level": 0,
  • "description": "string",
  • "photo_id": 0,
  • "coords_3d": { },
  • "public": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "type": "string",
  • "inspection": 0,
  • "name": "string",
  • "number": 0,
  • "data": { },
  • "severity_level": 0,
  • "description": "string",
  • "user": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "photo_id": 0,
  • "coords_3d": { },
  • "public": true,
  • "is_visible": true
}

Get a list of annotation types

Summary

Returns a list of all of the user's annotation types (unique) together with a list of default types

Responses

Response samples

Content type
application/json
{
  • "type": "string"
}

Get the Annotation information

Summary

Returns the detailed information about a specific Annotation, including its Photo ID, Type, Inspection, Name, Number, Data, Severity Level, Description, User, Coords 3D, Creation Date and Update Date.

path Parameters
id
required
integer

A unique integer value identifying this annotation.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "type": "string",
  • "inspection": 0,
  • "name": "string",
  • "number": 0,
  • "data": { },
  • "severity_level": 0,
  • "description": "string",
  • "user": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "photo_id": 0,
  • "coords_3d": { },
  • "public": true,
  • "is_visible": true
}

Update an Annotation

Summary

Updates an existing Annotation. Since this is the PUT method, all of the fields will be overwritten with the new information. For partial updates, take a look at the PATCH method.

Updating an Annotation will automatically overwrite its updated_at field with the current date and time.

path Parameters
id
required
integer

A unique integer value identifying this annotation.

Request Body schema: application/json
type
required
string (Type) [ 1 .. 255 ] characters
inspection
required
integer (Inspection)
name
string (Name) [ 1 .. 255 ] characters Nullable
data
required
object (Data)
severity_level
integer (Severity level)
Default: 0
description
string (Description) Nullable
coords_3d
object (Coords 3d) Nullable
public
boolean (Public)
is_visible
boolean (Is visible)

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "inspection": 0,
  • "name": "string",
  • "data": { },
  • "severity_level": 0,
  • "description": "string",
  • "coords_3d": { },
  • "public": true,
  • "is_visible": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "type": "string",
  • "inspection": 0,
  • "name": "string",
  • "number": 0,
  • "data": { },
  • "severity_level": 0,
  • "description": "string",
  • "user": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "photo_id": 0,
  • "coords_3d": { },
  • "public": true,
  • "is_visible": true
}

Partially update an Annotation

Summary

Updates one or more fields on an existing Annotation. Updating an Annotation will automatically overwrite its updated_at field with the current date and time.

path Parameters
id
required
integer

A unique integer value identifying this annotation.

Request Body schema: application/json
type
required
string (Type) [ 1 .. 255 ] characters
inspection
required
integer (Inspection)
name
string (Name) [ 1 .. 255 ] characters Nullable
data
required
object (Data)
severity_level
integer (Severity level)
Default: 0
description
string (Description) Nullable
coords_3d
object (Coords 3d) Nullable
public
boolean (Public)
is_visible
boolean (Is visible)

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "inspection": 0,
  • "name": "string",
  • "data": { },
  • "severity_level": 0,
  • "description": "string",
  • "coords_3d": { },
  • "public": true,
  • "is_visible": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "type": "string",
  • "inspection": 0,
  • "name": "string",
  • "number": 0,
  • "data": { },
  • "severity_level": 0,
  • "description": "string",
  • "user": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "photo_id": 0,
  • "coords_3d": { },
  • "public": true,
  • "is_visible": true
}

Delete an Annotation

Summary

Deletes an existing Annotation.

path Parameters
id
required
integer

A unique integer value identifying this annotation.

Responses

assets

Get all Assets

Summary

Returns a list of all of the Assets created by the current user. Details about the Type and the associated Inspections are also included. Deleted assets will not be included in the list.

It's possible to filter assets by its name using the search query param.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Asset

Summary

Creates a new Asset. While doing so, it also creates a new Project Group in Pix4D Cloud and assigns the resulting ID to the project_group_id field.

Field description

Fields name and type are mandatory. The rest are optional.

Fields latitude and longitude are in decimal degrees format and accept up to 8 decimals.

Fields user, organization_uuid, project_group_id, created_at and updated_at are automatically filled by the back-end.

Asset types

Asset types can be:

ID Description Family
1 Self-support Telecom
2 Building Generic
3 Bridge Generic
4 Cooling tower Generic
5 Energy utility Generic
6 Other Generic
7 Transmission tower Generic
8 Rooftop Generic
9 Monopole Telecom
10 Guyed tower Telecom
11 Rooftop Telecom
12 Watertower Telecom
13 Offshore energy utility Generic
Request Body schema: application/json
name
required
string (Name) [ 1 .. 255 ] characters
type
required
integer (Type)
latitude
string <decimal> (Latitude)
longitude
string <decimal> (Longitude)
description
string (Description) Nullable

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": 0,
  • "latitude": "string",
  • "longitude": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "type": 0,
  • "latitude": "string",
  • "longitude": "string",
  • "user": 0,
  • "organization_uuid": "5d67373d-71ba-435a-bb8a-e71f4d7e2958",
  • "description": "string",
  • "inspections": [
    ],
  • "project_group_id": 0,
  • "project_group_uuid": "7a9e0e38-3831-4a3b-8d7a-ed2a940545bb",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get all Asset Types

Summary

Returns the list of available Asset types.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Asset information

Summary

Returns information about a specific Asset, including its Name, Type, Inspections, User, Organization UUID, Latitude, Longitude, Description, Creation Date and Update Date.

path Parameters
id
required
integer

A unique integer value identifying this asset.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "type": 0,
  • "latitude": "string",
  • "longitude": "string",
  • "user": 0,
  • "organization_uuid": "5d67373d-71ba-435a-bb8a-e71f4d7e2958",
  • "description": "string",
  • "inspections": [
    ],
  • "project_group_id": 0,
  • "project_group_uuid": "7a9e0e38-3831-4a3b-8d7a-ed2a940545bb",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an Asset

Summary

Updates an existing Asset's parameters. Since this is the PUT method, all of the fields will be overwritten with the new information. For partial updates, take a look at the PATCH method.

Updating an Asset will automatically overwrite its updated_at field with the current date and time.

path Parameters
id
required
integer

A unique integer value identifying this asset.

Request Body schema: application/json
name
string (Name) [ 1 .. 255 ] characters
latitude
string <decimal> (Latitude)
longitude
string <decimal> (Longitude)
description
string (Description) Nullable

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "latitude": "string",
  • "longitude": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "type": 0,
  • "latitude": "string",
  • "longitude": "string",
  • "user": 0,
  • "organization_uuid": "5d67373d-71ba-435a-bb8a-e71f4d7e2958",
  • "description": "string",
  • "inspections": [
    ],
  • "project_group_id": 0,
  • "project_group_uuid": "7a9e0e38-3831-4a3b-8d7a-ed2a940545bb",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Partially update an Asset

Summary

Update one or more fields on an existing Asset. Updating an Asset will automatically overwrite its updated_at field with the current date and time.

path Parameters
id
required
integer

A unique integer value identifying this asset.

Request Body schema: application/json
name
string (Name) [ 1 .. 255 ] characters
latitude
string <decimal> (Latitude)
longitude
string <decimal> (Longitude)
description
string (Description) Nullable

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "latitude": "string",
  • "longitude": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "type": 0,
  • "latitude": "string",
  • "longitude": "string",
  • "user": 0,
  • "organization_uuid": "5d67373d-71ba-435a-bb8a-e71f4d7e2958",
  • "description": "string",
  • "inspections": [
    ],
  • "project_group_id": 0,
  • "project_group_uuid": "7a9e0e38-3831-4a3b-8d7a-ed2a940545bb",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an Asset

Summary

Deletes an existing Asset. While doing so, it also deletes the Project Group it's linked to in Pix4D Cloud.

IMPORTANT: The Asset will be deleted only if all their inspections are in stable statuses. In that case the inspections will be deleted too.

path Parameters
id
required
integer

A unique integer value identifying this asset.

Responses

Get all Inspections of an Asset

Summary

Returns a list of all of the Inspections of an Asset.

path Parameters
id
required
integer

A unique integer value identifying this asset.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "project_id": 0,
  • "project_uuid": "1de37675-f868-4726-bb1d-b08d89f463f9",
  • "app_source": "inspect",
  • "can_retry": true,
  • "retry_of": 0,
  • "retries": [
    ],
  • "asset": 0,
  • "status": 0,
  • "additional_statuses": {
    },
  • "pcs_task_uuid": "b0fd4e5e-bcab-462c-9bf5-906c59a263b6",
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "is_main": true,
  • "base_plate_location": { },
  • "top_point_location": { },
  • "base_plate_size": 0,
  • "processing_parameters": {
    },
  • "processing_backend": "mapper",
  • "report_status": "not available",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

inspections

Get all Inspections

Summary

Returns a list of all of the Inspections created by the current user. Details about the Type are also included. Inspections marked as deleted will not be included in the list.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Inspection

Summary

Creates a new Inspection. While doing so, it also creates a new Project in Pix4D Cloud and assigns the resulting ID to the project_id field.

It is also possible to create a inspection for a new asset adding the field new_asset setted to True and at least the mandatory fields of the asset creation (type and name) inside an asset field.

The inspection will be created automatically with New status.

Field description

Fields asset and processing_parameters are mandatory when creating an inspection. The rest are optional.

The field asset must be an existing Asset's ID.

The field inspection_date must have a date and a time with format yyyy-mm-dd hh:mm → Example: 2019-09-10 21:45

The field processing_parameters must contain a JSON object with the following values:

{
    "is_video": <boolean>,
    "generate_point_cloud": <boolean>,
    "clip_point_cloud": <boolean>,
    "clipping_radius": <int>,
    "generate_mesh": <boolean>,
    "generate_dsm": <boolean>,
    "generate_ortho": <boolean>
    "detect_antennas": <boolean>,
    "detect_rust": <boolean>,
    "roof_segmentation": <boolean>
}

Fields project_id, status, additional_statuses, report_status, created_at and updated_at are automatically filled by the back-end.

Inspection status

The Inspection Status can be:

ID Description
1 New
2 Uploading input files
3 Analyzing input images
4 Photogrammetry processing
5 Clipping point cloud
7 Processing completed
12 Extracting video images
13 ERROR - Uploading input files
14 ERROR - Extracting video images
15 ERROR - Analyzing input images
16 ERROR - Photogrammetry processing
17 ERROR - Clipping point cloud
19 ERROR - Not enough valid images
20 Waiting for processing
24 Data purged
25 Camera processing
27 Demo
Request Body schema: application/json
asset
required
integer (Asset)
inspection_date
string <date-time> (Inspection date) Nullable
description
string (Description) Nullable
name
string (Name) Nullable
object
Default: {"generate_point_cloud":true}
processing_backend
string (Processing backend)
Enum: "mapper" "vortex"

Responses

Request samples

Content type
application/json
{
  • "asset": 0,
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "processing_parameters": {
    },
  • "processing_backend": "mapper"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "project_id": 0,
  • "project_uuid": "1de37675-f868-4726-bb1d-b08d89f463f9",
  • "app_source": "inspect",
  • "can_retry": true,
  • "retry_of": 0,
  • "retries": [
    ],
  • "asset": 0,
  • "status": 0,
  • "additional_statuses": {
    },
  • "pcs_task_uuid": "b0fd4e5e-bcab-462c-9bf5-906c59a263b6",
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "is_main": true,
  • "base_plate_location": { },
  • "top_point_location": { },
  • "base_plate_size": 0,
  • "processing_parameters": {
    },
  • "processing_backend": "mapper",
  • "report_status": "not available",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get all Statuses

Summary

Returns the list of available additional statuses.

ID Description
1 Inventory automatic detection pending
2 Inventory automatic detection
3 Inventory review pending
4 Inventory review ongoing
5 Inventory review completed
6 Inventory review completed without compatible inventory
7 ERROR - Inventory automatic detection
8 ERROR - Inventory: No tower
9 WARNING - Inventory: Borderline quality
10 ERROR - Inventory: Insufficient quality
11 Rust analysis pending
12 Rust analysis ongoing
13 Rust analysis completed
14 Rust analysis error

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get all Inspection Statuses

Summary

Returns the list of availabe Inspection statuses.

ID Description
1 New
2 Uploading input files
3 Analyzing input images
4 Photogrammetry processing
5 Clipping point cloud
7 Processing completed
12 Extracting video images
13 ERROR - Uploading input files
14 ERROR - Extracting video images
15 ERROR - Analyzing input images
16 ERROR - Photogrammetry processing
17 ERROR - Clipping point cloud
19 ERROR - Not enough valid images
20 Waiting for processing
24 Data purged
25 Camera processing
27 Demo

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Inspection information

Summary

Returns detailed information about a specific Inspection, including its Asset, Project ID, Project UUID, Status, Additional Status, App Source PCS Task UUID (last PCS task executed for the inspection), User, the Asset it belongs to, if it can be retried, if it is a Retry of other Inspection or is it has other child inspections as Retries, if it is the Main Inspection of the bundle of Retries, Base Plate Location, Top Point Location, Base Plate Size, Description, Name, Ground Reference Altitude, Processing Parameters,Processing Backend, Report Status, Inspection Date, Creation Date and Update Date.

The Ground Reference Altitude field is in Metric System.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "project_id": 0,
  • "project_uuid": "1de37675-f868-4726-bb1d-b08d89f463f9",
  • "app_source": "inspect",
  • "can_retry": true,
  • "retry_of": 0,
  • "retries": [
    ],
  • "asset": 0,
  • "status": 0,
  • "additional_statuses": {
    },
  • "pcs_task_uuid": "b0fd4e5e-bcab-462c-9bf5-906c59a263b6",
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "is_main": true,
  • "base_plate_location": { },
  • "top_point_location": { },
  • "base_plate_size": 0,
  • "processing_parameters": {
    },
  • "processing_backend": "mapper",
  • "report_status": "not available",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an Inspection

Summary

Updates an existing Inspection's parameters. Since this is the PUT method, all of the fields will be overwritten with the new information. For partial updates, take a look at the PATCH method.

Updating an Inspection will automatically overwrite its updated_at field with the current date and time.

IMPORTANT An automatic email will be sent to the user when a status is changed to certain values (inspection started, inspection finished, error). If you don't want to send this email add this query parameter to the URL: skip_email=true

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Request Body schema: application/json
status
integer (Status)
object (additional_statuses)
pcs_task_uuid
string <uuid> (Pcs task uuid) Nullable
inspection_date
string <date-time> (Inspection date) Nullable
description
string (Description) Nullable
name
string (Name) Nullable
base_plate_location
object (Base plate location) Nullable
top_point_location
object (Top point location) Nullable
base_plate_size
number (Base plate size) >= 0 Nullable
report_status
string (Report status)
Enum: "not available" "processing" "available" "error"

Responses

Request samples

Content type
application/json
{
  • "status": 0,
  • "additional_statuses": {
    },
  • "pcs_task_uuid": "b0fd4e5e-bcab-462c-9bf5-906c59a263b6",
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "base_plate_location": { },
  • "top_point_location": { },
  • "base_plate_size": 0,
  • "report_status": "not available"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "project_id": 0,
  • "project_uuid": "1de37675-f868-4726-bb1d-b08d89f463f9",
  • "app_source": "inspect",
  • "can_retry": true,
  • "retry_of": 0,
  • "retries": [
    ],
  • "asset": 0,
  • "status": 0,
  • "additional_statuses": {
    },
  • "pcs_task_uuid": "b0fd4e5e-bcab-462c-9bf5-906c59a263b6",
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "is_main": true,
  • "base_plate_location": { },
  • "top_point_location": { },
  • "base_plate_size": 0,
  • "processing_parameters": {
    },
  • "processing_backend": "mapper",
  • "report_status": "not available",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Partially update an Inspection

Summary

Updates one or more fields on an existing Inspection. Updating an Inspection will automatically overwrite its updated_at field with the current date and time.

IMPORTANT An automatic email will be sent to the user when a status is changed to certain values (inspection started, inspection finished, error). If you don't want to send this email add this query parameter to the URL: skip_email=true

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Request Body schema: application/json
status
integer (Status)
object (additional_statuses)
pcs_task_uuid
string <uuid> (Pcs task uuid) Nullable
inspection_date
string <date-time> (Inspection date) Nullable
description
string (Description) Nullable
name
string (Name) Nullable
base_plate_location
object (Base plate location) Nullable
top_point_location
object (Top point location) Nullable
base_plate_size
number (Base plate size) >= 0 Nullable
report_status
string (Report status)
Enum: "not available" "processing" "available" "error"

Responses

Request samples

Content type
application/json
{
  • "status": 0,
  • "additional_statuses": {
    },
  • "pcs_task_uuid": "b0fd4e5e-bcab-462c-9bf5-906c59a263b6",
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "base_plate_location": { },
  • "top_point_location": { },
  • "base_plate_size": 0,
  • "report_status": "not available"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "project_id": 0,
  • "project_uuid": "1de37675-f868-4726-bb1d-b08d89f463f9",
  • "app_source": "inspect",
  • "can_retry": true,
  • "retry_of": 0,
  • "retries": [
    ],
  • "asset": 0,
  • "status": 0,
  • "additional_statuses": {
    },
  • "pcs_task_uuid": "b0fd4e5e-bcab-462c-9bf5-906c59a263b6",
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "is_main": true,
  • "base_plate_location": { },
  • "top_point_location": { },
  • "base_plate_size": 0,
  • "processing_parameters": {
    },
  • "processing_backend": "mapper",
  • "report_status": "not available",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an Inspection

Summary

Deletes an existing Inspection if it is in one of the stable statuses. While doing so, it also deletes the Project it's linked to in Pix4D Cloud.

IMPORTANT If an inspection marked as mainis deleted, its related inspections are going to be deleted too.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Get all Annotations of an Inspection

Summary

Returns a list of all of the Annotations of an Inspection.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "type": "string",
  • "inspection": 0,
  • "name": "string",
  • "number": 0,
  • "data": { },
  • "severity_level": 0,
  • "description": "string",
  • "user": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "photo_id": 0,
  • "coords_3d": { },
  • "public": true,
  • "is_visible": true
}

Get the bundle of Inspections related to an Inspection

Summary

Returns a bundle of inspections related to the queried one.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "project_id": 0,
  • "project_uuid": "1de37675-f868-4726-bb1d-b08d89f463f9",
  • "app_source": "inspect",
  • "can_retry": true,
  • "retry_of": 0,
  • "retries": [
    ],
  • "asset": 0,
  • "status": 0,
  • "additional_statuses": {
    },
  • "pcs_task_uuid": "b0fd4e5e-bcab-462c-9bf5-906c59a263b6",
  • "inspection_date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "name": "string",
  • "is_main": true,
  • "base_plate_location": { },
  • "top_point_location": { },
  • "base_plate_size": 0,
  • "processing_parameters": {
    },
  • "processing_backend": "mapper",
  • "report_status": "not available",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a list of Cameras of an Inspection

Summary

Returns a JSON array with the all of the cameras from an Inspection.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "photo_id": 0,
  • "filename": "string",
  • "location": { },
  • "mission": "string",
  • "dimensions": { },
  • "quaternions": { },
  • "is_master": true,
  • "is_reviewed": true,
  • "is_visible": true
}

Get inspection extras

Summary

Returns extra information related to the inspection.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "coordinate_system": "string",
  • "offset_3d_xyz": [
    ]
}

Get inspection inputs

Summary

Returns a URL to download the original input files to create the inspection.

The inputs will be compressed in a ZIP file that has to be generated first. This means that this endpoint must be called twice: once to generate the ZIP file and a second time after a few minutes to obtain the URL for the file download.

This endpoint returns the following HTTP status codes:

  • 200: If the ZIP file exists. The URL is specified in the response body.
  • 202: If the ZIP file does not exist. This will start the file generation.
  • 404: If the inspection does not exist.

NOTE: Once the ZIP file is generated, an e-mail is going to be sent to the user that created the inspection.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "url": "string"
}

Get all Inventory Items of an Inspection

Summary

Returns a list of all of the Inventory Items of an Inspection.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": 0,
  • "name": "string",
  • "model_name": "string",
  • "weight": "string",
  • "urls": { },
  • "photo_id": 0,
  • "point_of_view": [ ],
  • "coords_2d": { },
  • "photo_projection": { },
  • "coords_3d": [ ],
  • "public": true,
  • "visible": true,
  • "device_status": "active",
  • "source": "automatic",
  • "model_type": "point",
  • "offset_xyz": { },
  • "plumb": -90,
  • "azimuth": 0,
  • "downtilt": -90,
  • "height": 0,
  • "width": 0,
  • "depth": 0,
  • "custom_fields": [
    ],
  • "template": 0,
  • "inspection": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Measurements of an Inspection

Summary

Returns a list with all the Measurements of an Inspection.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Create Measurements for an Inspection

Summary

Saves a json with the new Measurements of an Inspection.

Example.

{
    "annotations": [
        {
            "properties": {
                "name": "Polygon",
                "description": "Polygon 1",
                "color_fill": "#448AFFFF",
                "color": "#448AFFFF",
                "visible": true,
                "camera_position": [465449.95829250535,4503704.291471222,860.1325480958155]
            },
            "tags": [],
            "geometry": {
                "coordinates": [
                    [
                        [
                            465450.179000,
                            4503709.151000,
                            858.397000
                        ],
                        [
                            465449.533000,
                            4503708.223000,
                            858.457000
                        ],
                        [
                            465449.517000,
                            4503708.601000,
                            857.672000
                        ]
                    ]
                ],
                "bbox": [0,0,0,0,0,0],
                "type": "Polygon"
            }
        }
    ]
}
path Parameters
id
required
integer

A unique integer value identifying this inspection.

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "annotations": [
    ]
}

Response samples

Content type
application/json
{
  • "annotations": [
    ]
}

Update a Measurement of an Inspection

Summary

Updates a specific Measurement of an Inspection.

path Parameters
annotation_id
required
string
id
required
integer

A unique integer value identifying this inspection.

Request Body schema: application/json
properties
required
object (Properties)
tags
required
Array of strings
geometry
required
object (Geometry)

Responses

Request samples

Content type
application/json
{
  • "properties": { },
  • "tags": [
    ],
  • "geometry": { }
}

Response samples

Content type
application/json
{
  • "properties": { },
  • "extension": { },
  • "id": "string",
  • "tags": [
    ],
  • "entity_type": "string",
  • "entity_id": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "geometry": { },
  • "modified": "2019-08-24T14:15:22Z"
}

Delete a Measurement of an Inspection

Summary

Deletes a specific Measurement of an Inspection.

path Parameters
annotation_id
required
string
id
required
integer

A unique integer value identifying this inspection.

Responses

Get inspection outputs

Summary

Returns a list of all the inspection's outputs -- files built from the processing results along with their url to download.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "output_type": "string",
  • "url": "string"
}

Process an inspection

Summary

Starts an inspection pcs task. The flow ID is stored in the inspection row in the backend DB.

Pre-requisites to process an inspection:

  • The images must be already uploaded to S3
  • The inspection must be in one of the following status: New, Uploading input files or Waiting for processing.

IMPORTANT: The allowance resources will be consumed when starting the processing of an inspection. Not before, not after.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Register images for an Inspection

Registers a list of images to be used by the Inspection.

The maximum number of images to register is 500 per call. If your Inspection has more than 500 images, you can call this endpoint multiple times.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Request Body schema: application/json
image_keys
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "image_keys": [
    ]
}

Response samples

Content type
application/json
{
  • "nb_images_registered": 0
}

Generate an Inspection report

Starts the generation of a json and a pdf that contain all the information about an inspection, including the asset, annotations, inventory and user data.

The status of the report generation will be updated in the report_status field of the Inspection.

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Request Body schema: application/json
include_email
boolean (Include email)
Default: true
include_annotations
boolean (Include annotations)
Default: true
include_polygon_measurements
boolean (Include polygon measurements)
Default: true
include_line_measurements
boolean (Include line measurements)
Default: true
include_inventory_items
boolean (Include inventory items)
Default: true
include_only_visible
boolean (Include only visible)
Default: false
include_sharetoken
boolean (Include sharetoken)
Default: true
include_2d_plans
boolean (Include 2d plans)
Default: false
extra_remarks
string (Extra remarks) Nullable

Responses

Request samples

Content type
application/json
{
  • "include_email": true,
  • "include_annotations": true,
  • "include_polygon_measurements": true,
  • "include_line_measurements": true,
  • "include_inventory_items": true,
  • "include_only_visible": false,
  • "include_sharetoken": true,
  • "include_2d_plans": false,
  • "extra_remarks": "string"
}

Response samples

Content type
application/json
{ }

Gets AWS S3 credentials

Summary

Returns AWS S3 temporary credentials to access to the files of an Inspection

The parameters access_key, secret_key, session_token and region are required to start a session with any of the libraries that AWS provides to work with S3 (e.g. boto3)

The bucket parameter is also needed once started a session.

The key returned is the only place in s3 where you are allowed to write for that project with the returned credentials. When uploading files (and registering them), make sure that all your images path are prefixed with this location. (e.g. user-c89f1e11-ed76-4ded-bbdb-edddc0816250/project-123456/IMAGE_1.JPG)

IMPORTANT: Image uploading must be performed only before the processing starts (Uploading status)

path Parameters
id
required
integer

A unique integer value identifying this inspection.

Responses

Response samples

Content type
application/json
{
  • "access_key": "string",
  • "secret_key": "string",
  • "session_token": "string",
  • "expiration": "2019-08-24T14:15:22Z",
  • "bucket": "string",
  • "key": "string",
  • "server_time": "2019-08-24T14:15:22Z",
  • "region": "string"
}

inventory

Create a new Inventory Item

Summary

Creates a new Inventory Item.

Field description

Fields inspection, template, point_of_view, coords_3d are mandatory. Among them, point_of_view and coords_3d must be set in JSON format.

Fields urls, coords_2d and photo_projection are optional and must be set in JSON format.

Fields uuid, number, custom_fields, created_at and updated_at are automatically filled by the back-end.

Inventory Templates

Default inventory templates:

ID Description
1 panel
2 microwave
3 ancillary box
7 manual colineal
8 manual yagi
9 manual mount
10 manual cabinet
Request Body schema: application/json
name
string (Name) <= 255 characters Nullable
model_name
string (Model name) <= 255 characters Nullable
weight
string (Weight) <= 255 characters Nullable
urls
object (Urls) Nullable
photo_id
integer (Photo id) [ 0 .. 2147483647 ] Nullable
point_of_view
object (Point of view)
Default: []
coords_2d
object (Coords 2d) Nullable
photo_projection
object (Photo projection) Nullable
coords_3d
object (Coords 3d)
Default: []
public
boolean (Public)
visible
boolean (Visible)
device_status
string (Device status)
Enum: "active" "inactive" "future_installation"
source
string (Source)
Enum: "automatic" "manual"
model_type
string (Model type)
Enum: "point" "cube"
offset_xyz
object (Offset xyz) Nullable
plumb
number (Plumb) [ -90 .. 90 ] Nullable
azimuth
number (Azimuth) [ 0 .. 360 ] Nullable
downtilt
number (Downtilt) [ -90 .. 90 ] Nullable
height
number (Height) [ 0 .. 99 ] Nullable
width
number (Width) [ 0 .. 99 ] Nullable
depth
number (Depth) [ 0 .. 99 ] Nullable
template
required
integer (Template)
inspection
required
integer (Inspection)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "model_name": "string",
  • "weight": "string",
  • "urls": { },
  • "photo_id": 0,
  • "point_of_view": [ ],
  • "coords_2d": { },
  • "photo_projection": { },
  • "coords_3d": [ ],
  • "public": true,
  • "visible": true,
  • "device_status": "active",
  • "source": "automatic",
  • "model_type": "point",
  • "offset_xyz": { },
  • "plumb": -90,
  • "azimuth": 0,
  • "downtilt": -90,
  • "height": 0,
  • "width": 0,
  • "depth": 0,
  • "template": 0,
  • "inspection": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": 0,
  • "name": "string",
  • "model_name": "string",
  • "weight": "string",
  • "urls": { },
  • "photo_id": 0,
  • "point_of_view": [ ],
  • "coords_2d": { },
  • "photo_projection": { },
  • "coords_3d": [ ],
  • "public": true,
  • "visible": true,
  • "device_status": "active",
  • "source": "automatic",
  • "model_type": "point",
  • "offset_xyz": { },
  • "plumb": -90,
  • "azimuth": 0,
  • "downtilt": -90,
  • "height": 0,
  • "width": 0,
  • "depth": 0,
  • "custom_fields": [
    ],
  • "template": 0,
  • "inspection": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get the Inventory Template Field information

Summary

Returns detailed information about a specific Inventory Template Field, including its ID, Name, Template, Default Value and Field Type.

path Parameters
id
required
integer

A unique integer value identifying this inventory template field.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "template": {
    },
  • "field_type": "str",
  • "user": 0,
  • "default_value": { }
}

Update an Inventory Template Field

Summary

Updates an existing Inventory Template Field. Since this is the PUT method, all of the fields will be overwritten with the new information. For partial updates, take a look at the PATCH method.

path Parameters
id
required
integer

A unique integer value identifying this inventory template field.

Request Body schema: application/json
name
required
string (Name) [ 1 .. 255 ] characters
template
required
integer (Template)
field_type
required
string (Field type)
Enum: "str" "float" "int" "list" "dict" "bool"
user
integer (User) Nullable
default_value
object (Default value) Nullable

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "template": 0,
  • "field_type": "str",
  • "user": 0,
  • "default_value": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "template": 0,
  • "field_type": "str",
  • "user": 0,
  • "default_value": { }
}

Partially update an Inventory Template Field

Summary

Updates one or more fields on an existing Inventory Template Field.

path Parameters
id
required
integer

A unique integer value identifying this inventory template field.

Request Body schema: application/json
name
required
string (Name) [ 1 .. 255 ] characters
template
required
integer (Template)
field_type
required
string (Field type)
Enum: "str" "float" "int" "list" "dict" "bool"
user
integer (User) Nullable
default_value
object (Default value) Nullable

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "template": 0,
  • "field_type": "str",
  • "user": 0,
  • "default_value": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "template": 0,
  • "field_type": "str",
  • "user": 0,
  • "default_value": { }
}

Delete an Inventory Template Field

Summary

Deletes an existing Inventory Template Field.

path Parameters
id
required
integer

A unique integer value identifying this inventory template field.

Responses

Get Inventory Templates

Summary

Returns a list with Inventory Templates a user owns along with their Inventory Template Fields.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the Inventory Item information

Summary

Returns the detailed information about a specific Inventory Item, including its UUID, Type ID, Number, Name, User, Model Name, Altitude, Latitude, Longitude, Inspection, Weight, URLs, Type, Photo ID, Point of View, Coords 2D, Photo Projection, Coords 3D, Public, Visible, Source, Device Status, Model Type, Offset xyz, Plumb, Azimuth, Downtilt, Height, Width, Depth, Custom Fields, Creation Date and Update Date.

The following fields are in Metric System: Altitude, Offset xyz, Height, Width and Depth

path Parameters
id
required
integer

A unique integer value identifying this inventory item.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": 0,
  • "name": "string",
  • "model_name": "string",
  • "weight": "string",
  • "urls": { },
  • "photo_id": 0,
  • "point_of_view": [ ],
  • "coords_2d": { },
  • "photo_projection": { },
  • "coords_3d": [ ],
  • "public": true,
  • "visible": true,
  • "device_status": "active",
  • "source": "automatic",
  • "model_type": "point",
  • "offset_xyz": { },
  • "plumb": -90,
  • "azimuth": 0,
  • "downtilt": -90,
  • "height": 0,
  • "width": 0,
  • "depth": 0,
  • "custom_fields": [
    ],
  • "template": 0,
  • "inspection": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an Inventory Item

Summary

Updates an existing Inventory Item. Since this is the PUT method, all of the fields will be overwritten with the new information. For partial updates, take a look at the PATCH method. Updating an Inventory Item will automatically overwrite its updated_at field with the current date and time.

IMPORTANT To update the custom_fields of an Inventory Item, it is needed to send their id along with the field_type, name, and value. Each custom field not included in the custom_fields array will be deleted. In other words: sending an empty array implies to delete all the custom fields of an Inventory Item, but updating an Inventory Item without including the custom_fields array will not perform any change in the custom fields. In the same way if this array includes some new custom fields without id, they will be created and their ids will be included in the response along with the old ones.

path Parameters
id
required
integer

A unique integer value identifying this inventory item.

Request Body schema: application/json
number
integer (Number) [ 0 .. 2147483647 ] Nullable
name
string (Name) <= 255 characters Nullable
model_name
string (Model name) <= 255 characters Nullable
weight
string (Weight) <= 255 characters Nullable
urls
object (Urls) Nullable
photo_id
integer (Photo id) [ 0 .. 2147483647 ] Nullable
point_of_view
object (Point of view)
Default: []
coords_2d
object (Coords 2d) Nullable
photo_projection
object (Photo projection) Nullable
coords_3d
object (Coords 3d)
Default: []
public
boolean (Public)
visible
boolean (Visible)
device_status
string (Device status)
Enum: "active" "inactive" "future_installation"
source
string (Source)
Enum: "automatic" "manual"
model_type
string (Model type)
Enum: "point" "cube"
offset_xyz
object (Offset xyz) Nullable
plumb
number (Plumb) [ -90 .. 90 ] Nullable
azimuth
number (Azimuth) [ 0 .. 360 ] Nullable
downtilt
number (Downtilt) [ -90 .. 90 ] Nullable
height
number (Height) [ 0 .. 99 ] Nullable
width
number (Width) [ 0 .. 99 ] Nullable
depth
number (Depth) [ 0 .. 99 ] Nullable
Array of objects
template
required
integer (Template)
inspection
required
integer (Inspection)

Responses

Request samples

Content type
application/json
{
  • "number": 0,
  • "name": "string",
  • "model_name": "string",
  • "weight": "string",
  • "urls": { },
  • "photo_id": 0,
  • "point_of_view": [ ],
  • "coords_2d": { },
  • "photo_projection": { },
  • "coords_3d": [ ],
  • "public": true,
  • "visible": true,
  • "device_status": "active",
  • "source": "automatic",
  • "model_type": "point",
  • "offset_xyz": { },
  • "plumb": -90,
  • "azimuth": 0,
  • "downtilt": -90,
  • "height": 0,
  • "width": 0,
  • "depth": 0,
  • "custom_fields": [
    ],
  • "template": 0,
  • "inspection": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": 0,
  • "name": "string",
  • "model_name": "string",
  • "weight": "string",
  • "urls": { },
  • "photo_id": 0,
  • "point_of_view": [ ],
  • "coords_2d": { },
  • "photo_projection": { },
  • "coords_3d": [ ],
  • "public": true,
  • "visible": true,
  • "device_status": "active",
  • "source": "automatic",
  • "model_type": "point",
  • "offset_xyz": { },
  • "plumb": -90,
  • "azimuth": 0,
  • "downtilt": -90,
  • "height": 0,
  • "width": 0,
  • "depth": 0,
  • "custom_fields": [
    ],
  • "template": 0,
  • "inspection": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Partially update a Inventory Item

Summary

Updates one or more fields on an existing Inventory Item. Updating a Inventory Item will automatically overwrite its updated_at field with the current date and time.

IMPORTANT To update the custom_fields of an Inventory Item, it is needed to send their id along with the field_type, name, and value. Each custom field not included in the custom_fields array will be deleted. In other words: sending an empty array implies to delete all the custom fields of an Inventory Item, but updating an Inventory Item without including the custom_fields array will not perform any change in the custom fields. In the same way if this array includes some new custom fields without id, they will be created and their ids will be included in the response along with the old ones.

path Parameters
id
required
integer

A unique integer value identifying this inventory item.

Request Body schema: application/json
name
string (Name) <= 255 characters Nullable
model_name
string (Model name) <= 255 characters Nullable
weight
string (Weight) <= 255 characters Nullable
urls
object (Urls) Nullable
photo_id
integer (Photo id) [ 0 .. 2147483647 ] Nullable
point_of_view
object (Point of view)
Default: []
coords_2d
object (Coords 2d) Nullable
photo_projection
object (Photo projection) Nullable
coords_3d
object (Coords 3d)
Default: []
public
boolean (Public)
visible
boolean (Visible)
device_status
string (Device status)
Enum: "active" "inactive" "future_installation"
source
string (Source)
Enum: "automatic" "manual"
model_type
string (Model type)
Enum: "point" "cube"
offset_xyz
object (Offset xyz) Nullable
plumb
number (Plumb) [ -90 .. 90 ] Nullable
azimuth
number (Azimuth) [ 0 .. 360 ] Nullable
downtilt
number (Downtilt) [ -90 .. 90 ] Nullable
height
number (Height) [ 0 .. 99 ] Nullable
width
number (Width) [ 0 .. 99 ] Nullable
depth
number (Depth) [ 0 .. 99 ] Nullable
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "model_name": "string",
  • "weight": "string",
  • "urls": { },
  • "photo_id": 0,
  • "point_of_view": [ ],
  • "coords_2d": { },
  • "photo_projection": { },
  • "coords_3d": [ ],
  • "public": true,
  • "visible": true,
  • "device_status": "active",
  • "source": "automatic",
  • "model_type": "point",
  • "offset_xyz": { },
  • "plumb": -90,
  • "azimuth": 0,
  • "downtilt": -90,
  • "height": 0,
  • "width": 0,
  • "depth": 0,
  • "custom_fields": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "number": 0,
  • "name": "string",
  • "model_name": "string",
  • "weight": "string",
  • "urls": { },
  • "photo_id": 0,
  • "point_of_view": [ ],
  • "coords_2d": { },
  • "photo_projection": { },
  • "coords_3d": [ ],
  • "public": true,
  • "visible": true,
  • "device_status": "active",
  • "source": "automatic",
  • "model_type": "point",
  • "offset_xyz": { },
  • "plumb": -90,
  • "azimuth": 0,
  • "downtilt": -90,
  • "height": 0,
  • "width": 0,
  • "depth": 0,
  • "custom_fields": [
    ],
  • "template": 0,
  • "inspection": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an Inventory Item

Summary

Deletes an existing Inventory Item.

path Parameters
id
required
integer

A unique integer value identifying this inventory item.

Responses

sharetokens

Create a share token

Summary

Creates a share token that can be used for accessing an inspection and its related data without being authenticated in the usual way (jwt_token). The share token is created as enabled, to disable it use the PATCH/PUT method.

If the share token has the write option set to True, it's also possible to create, update and delete inventory items and annotations.

Request Body schema: application/json
inspection
required
integer (Inspection)
write
required
boolean (Write)

Responses

Request samples

Content type
application/json
{
  • "inspection": 0,
  • "write": true
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "enabled": true,
  • "write": true,
  • "creation_date": "2019-08-24T14:15:22Z"
}

Get the details of a share token

Summary

Returns the information of a share token if it belongs to the user, including if it is enabled or not, if it has write rights and also the creation date.

path Parameters
sharetoken
required
string

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "enabled": true,
  • "write": true,
  • "creation_date": "2019-08-24T14:15:22Z"
}

Update a share token

Summary

Enables or disables a share token and changes its write rights IMPORTANT: Only the user that created the share token can update it.

path Parameters
sharetoken
required
string
Request Body schema: application/json
enabled
boolean (Enabled)
write
boolean (Write)

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "write": true
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "enabled": true,
  • "write": true,
  • "creation_date": "2019-08-24T14:15:22Z"
}

Partially update a share token

Summary

Updates one or more features of a share token IMPORTANT: Only the user that created the share token can update it.

path Parameters
sharetoken
required
string
Request Body schema: application/json
inspection
required
integer (Inspection)
write
required
boolean (Write)

Responses

Request samples

Content type
application/json
{
  • "inspection": 0,
  • "write": true
}

Response samples

Content type
application/json
{
  • "inspection": 0,
  • "write": true
}

2d3dmapping

Get the correspondent 3d coordinates of a point in a photo

Summary

The camera is the id of the camera generated by the photo which point you want to get in the 3d coordinates.

The coords_2d must contain four points with values between 0 to 1, representing the position of a square in the photo as a percentage, being (0.0, 0.0) the upper left point of the photo and (1.0, 1.0) its bottom right one.

Example.

{
        "camera": 1,
        "coords_2d": [
            [
                0.44901315789473684,
                0.20443564967105254
            ],
            [
                0.44901315789473684,
                0.5358501233552632
            ],
            [
                0.6699561403508772,
                0.5358501233552632
            ],
            [
                0.6699561403508772,
                0.20443564967105254
            ]
        ]
}
Request Body schema: application/json
camera
required
integer (Camera) non-empty
coords_2d
required
object (Coords_2d)
Default: []

Responses

Request samples

Content type
application/json
{
  • "camera": 0,
  • "coords_2d": [ ]
}

Response samples

Content type
application/json
{
  • "coords_3d": [ ]
}