Skip to content

Overview of all Endpoints

The API base URL is: https://api.deepva.com/api/v1

Perform CRUD operations on the core-resources in REST style.

Visual Mining Jobs

Visual Mining Jobs are available on the Jobs-Endpoint.

/Jobs

GET /jobs/

Retrieve a list of Visual Mining Jobs

Returns: Pagination object with list of Job objects

URL Parameters:

offset - The index of the first object in the list to be returned, starting with 0 (default: 0)

limit - A limit on the number of objects to be returned (default: 10)

search - List jobs by id and tag

tag - List jobs by tag

See Pagination and Filter for more information.

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/jobs/
import requests

headers = {"Content-Type": "application/json",
               "Authorization": f"Key {your_api_key}"}       
response = requests.get(f"https://api.deepva.com/api/v1/jobs/",
                        headers=headers)               
if response.status_code == 200:
    jobs = response.json()
    print(jobs)
else:
    print(f"Error: {response.status_code}")

Example response:

{
    "total": 1,
    "offset": 0,
    "limit": 10,
    "next": "http://api.deepva.com/api/v1/datasets/?limit=5&offset=10",
    "prev": "http://api.deepva.com/api/v1/datasets/?limit=5&offset=0",
    "data": [
        {
          "id": "6b5195d6-cc05-4a99-a293-8d73be0aa37f",
          "tag": "",
          "state": "completed",
          "progress": 1.0,
          "duration": 0.2,
          "time_created": "2019-08-12 08:14:28.430144",
          "time_started": "2019-08-12 08:14:29.510771",
          "time_completed": "2019-08-12 08:14:29.530825",
          "sources": [
              "https://demo.deepva.com/demo1.jpg"
          ],
          "modules": {
              "object_scene_recognition": {
                "model": "general"
              }
          },
          "result": {
              "detailed_link": "https://api.deepva.com/v1/jobs/6b5195d6-cc05-4a99-a293-8d73be0aa37f/detailed-results",
              "summary": [
                {
                    "source": "https://demo.deepva.com/demo1.jpg",
                    "media_type": "image",
                    "info": {},
                    "items": [
                        {
                            "type": "object",
                            "label": "Indoor"
                        },
                        {
                            "type": "object",
                            "label": "Chair"
                        },
                        {
                            "type": "object",
                            "label": "Furniture"
                        },
                        {
                            "type": "object",
                            "label": "Cushion"
                        }
                    ]
                }
              ]
        }
    ]
}
GET /jobs/{JOB_ID}/

Retrieves a single Visual Mining Jobs by its ID

Returns: Job object

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/jobs/{job_id}/
import requests

headers = {"Content-Type": "application/json",
               "Authorization": f"Key {your_api_key}"}       
response = requests.get(f"https://api.deepva.com/api/v1/jobs/{job_id}/",
                        headers=headers)               
if response.status_code == 200:
    job = response.json()
    print(job)
else:
    print(f"Error: {response.status_code}")

Example response:

{
  "id": "6b5195d6-cc05-4a99-a293-8d73be0aa37f",
  "tag": "",
  "state": "completed",
  "progress": 1.0,
  "duration": 0.2,
  "time_created": "2019-08-12 08:14:28.430144",
  "time_started": "2019-08-12 08:14:29.510771",
  "time_completed": "2019-08-12 08:14:29.530825",
  "sources": [
      "https://demo.deepva.com/demo1.jpg"
  ],
  "modules": {
      "object_scene_recognition": {
        "model": "general"
      }
  },
  "result": {
      "detailed_link": "https://api.deepva.com/v1/jobs/6b5195d6-cc05-4a99-a293-8d73be0aa37f/detailed-results",
      "summary": [
        {
            "source": "https://demo.deepva.com/demo1.jpg",
            "media_type": "image",
            "info": {},
            "items": [
                {
                    "type": "object",
                    "label": "Indoor"
                },
                {
                    "type": "object",
                    "label": "Chair"
                },
                {
                    "type": "object",
                    "label": "Furniture"
                },
                {
                    "type": "object",
                    "label": "Cushion"
                }
            ]
        }
      ]
}
POST /jobs/

Creates a new Visual Mining Job

Returns: Job object that has been created

Example request:

curl -d '{"sources": ["https://demo.deepva.com/demo1.jpg"], "modules": {"object_scene_recognition": {"model": "general"}}}' -H "Content-Type: application/json" -H "Authorization: Key {your-api-key}" -X POST https://api.deepva.com/api/v1/jobs/
# coming soon

Example response:

{
  "id": "3ad21bb4-774e-45e0-8c1f-15ec42037644",
  "tag": "",
  "state": "waiting",
  "errors": [],
  "progress": 0,
  "duration": 0,
  "time_created": "2020-08-14 14:21:20.777910",
  "time_started": null,
  "time_completed": null,
  "sources": [
    "https://demo.deepva.com/demo1.jpg"
  ],
  "modules": {
    "object_scene_recognition": {
      "model": "general",
      "state": "waiting"
    }
  },
  "result": {
    "detailed_link": "https://api.deepva.com/v1/jobs/3ad21bb4-774e-45e0-8c1f-15ec42037644/detailed-results/",
    "summary": []
  }
}

The Job has just been created. The state is "waiting" becasue it waits for processing by DeepVA. There is no result available yet. result.summary is empty.

You can request the Job by its ID and check the state: https://api.deepva.com/v1/jobs/3ad21bb4-774e-45e0-8c1f-15ec42037644/

DELETE /jobs/{JOB_ID}/

Deletes and aborts an existing Visual Mining Job

Returns: Message saying that the job has been deleted

Example request:

curl -H "Authorization: Key {your-api-key}" -X DELETE https://api.deepva.com/api/v1/jobs/{job_id}/
# coming soon

Example response:

{
    "message": "Job has been deleted"
}

/Detailed results

A Job object contains the result summary. For more detailed results (e.g. the position of identity or object in the video) you need to request the sub-endpoint: detailed-results.

GET /jobs/{JOB_ID}/detailed-results/

Retrieve detailed results of a single Visual Mining Jobs by its ID

Returns: Pagination object with list of DetailedResult objects

URL Parameters:

offset - The index of the first object in the list to be returned, starting with 0 (default: 0)

limit - A limit on the number of objects to be returned (default: 10)

See Pagination and Filter for more information.

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/jobs/{job_id}/detailed-results/
import requests

headers = {"Content-Type": "application/json",
               "Authorization": f"Key {your_api_key}"}       
response = requests.get(f"https://api.deepva.com/api/v1/jobs/{job_id}/detailed-results/",
                        headers=headers)               
if response.status_code == 200:
    results = response.json()
    print(results)
else:
    print(f"Error: {response.status_code}")

Example response:

{
    "total": 4,
    "offset": 0,
    "limit": 10,
    "next": "http://api.deepva.com/api/v1/jobs/21b61bd9-3d82-41a7-8cab-f154eaf6783c/detailed-results/?limit=10&offset=10",
    "prev": "http://api.deepva.com/api/v1/jobs/21b61bd9-3d82-41a7-8cab-f154eaf6783c/detailed-results/?limit=10&offset=0",
    "data": [
        {
            "media_type": "video",
            "frame_start": 12,
            "frame_end": 56,
            "source": "storage://Fad9kJ0jSI3swC6N5hVp",
            "module": "face_recognition",
            "meta": {
                "person": "Alexander Schwolow",
                "mean_distance": 0.93,
                "mean_similarity": 0.56
            },
            "time_start": 0.48,
            "time_end": 2.24,
            "tc_start": "00:00:12:00",
            "tc_end": "00:00:56:00",
            "detections": [
                {
                    "frame_index": 12,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.636,
                        "y": 0.165,
                        "w": 0.089,
                        "h": 0.226
                    }
                },
                {
                    "frame_index": 24,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.632,
                        "y": 0.169,
                        "w": 0.088,
                        "h": 0.222
                    }
                },
                {
                    "frame_index": 36,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.634,
                        "y": 0.157,
                        "w": 0.09,
                        "h": 0.235
                    }
                },
                {
                    "frame_index": 48,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.639,
                        "y": 0.161,
                        "w": 0.089,
                        "h": 0.233
                    }
                }
            ],
        },
        {
            "media_type": "video",
            "frame_start": 12,
            "frame_end": 56,
            "source": "storage://Fad9kJ0jSI3swC6N5hVp",
            "module": "face_recognition",
            "meta": {
                "person": "Vincenzo Grifo",
                "mean_distance": 0.88,
                "mean_similarity": 0.61
            },
            "time_start": 0.48,
            "time_end": 2.24,
            "tc_start": "00:00:12:00",
            "tc_end": "00:00:56:00",
            "detections": [
                {
                    "frame_index": 12,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.831,
                        "y": 0.146,
                        "w": 0.095,
                        "h": 0.222
                    }
                },
                {
                    "frame_index": 24,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.821,
                        "y": 0.139,
                        "w": 0.094,
                        "h": 0.213
                    }
                },
                {
                    "frame_index": 36,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.824,
                        "y": 0.135,
                        "w": 0.094,
                        "h": 0.211
                    }
                },
                {
                    "frame_index": 48,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.826,
                        "y": 0.133,
                        "w": 0.097,
                        "h": 0.211
                    }
                }
            ]
        },
        {
            "media_type": "video",
            "frame_start": 468,
            "frame_end": 668,
            "source": "storage://Fad9kJ0jSI3swC6N5hVp",
            "module": "face_recognition",
            "meta": {
                "person": "Julian Schuster",
                "mean_distance": 0.89,
                "mean_similarity": 0.6
            },
            "time_start": 18.72,
            "time_end": 26.72,
            "tc_start": "00:07:48:00",
            "tc_end": "00:11:08:00",
            "detections": [
                {
                    "frame_index": 468,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.546,
                        "y": 0.141,
                        "w": 0.219,
                        "h": 0.613
                    }
                },
                {
                    "frame_index": 480,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.532,
                        "y": 0.146,
                        "w": 0.226,
                        "h": 0.617
                    }
                },
                {
                    "frame_index": 492,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.561,
                        "y": 0.135,
                        "w": 0.222,
                        "h": 0.609
                    }
                },
                {
                    "frame_index": 504,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.569,
                        "y": 0.143,
                        "w": 0.219,
                        "h": 0.604
                    }
                },
                {
                    "frame_index": 516,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.554,
                        "y": 0.148,
                        "w": 0.22,
                        "h": 0.604
                    }
                },
                {
                    "frame_index": 528,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.558,
                        "y": 0.131,
                        "w": 0.223,
                        "h": 0.617
                    }
                },
                {
                    "frame_index": 540,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.578,
                        "y": 0.126,
                        "w": 0.22,
                        "h": 0.617
                    }
                },
                {
                    "frame_index": 552,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.567,
                        "y": 0.139,
                        "w": 0.222,
                        "h": 0.62
                    }
                },
                {
                    "frame_index": 564,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.553,
                        "y": 0.119,
                        "w": 0.221,
                        "h": 0.613
                    }
                },
                {
                    "frame_index": 576,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.529,
                        "y": 0.137,
                        "w": 0.224,
                        "h": 0.613
                    }
                },
                {
                    "frame_index": 588,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.576,
                        "y": 0.124,
                        "w": 0.215,
                        "h": 0.604
                    }
                },
                {
                    "frame_index": 600,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.568,
                        "y": 0.128,
                        "w": 0.215,
                        "h": 0.589
                    }
                },
                {
                    "frame_index": 612,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.56,
                        "y": 0.124,
                        "w": 0.218,
                        "h": 0.593
                    }
                },
                {
                    "frame_index": 624,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.559,
                        "y": 0.107,
                        "w": 0.218,
                        "h": 0.602
                    }
                },
                {
                    "frame_index": 636,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.571,
                        "y": 0.113,
                        "w": 0.219,
                        "h": 0.604
                    }
                },
                {
                    "frame_index": 648,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.555,
                        "y": 0.124,
                        "w": 0.221,
                        "h": 0.602
                    }
                },
                {
                    "frame_index": 660,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.546,
                        "y": 0.109,
                        "w": 0.215,
                        "h": 0.598
                    }
                }
            ]
        },
        {
            "media_type": "video",
            "frame_start": 720,
            "frame_end": 792,
            "source": "storage://Fad9kJ0jSI3swC6N5hVp",
            "module": "face_recognition",
            "meta": {
                "person": "unknown",
                "closest_person": "Charlie Manuel",
                "mean_distance": 1.05,
                "mean_similarity": 0.45
            },
            "time_start": 28.8,
            "time_end": 31.68,
            "tc_start": "00:12:00:00",
            "tc_end": "00:13:12:00",
            "detections": [
                {
                    "frame_index": 720,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.499,
                        "y": 0.281,
                        "w": 0.104,
                        "h": 0.3
                    }
                },
                {
                    "frame_index": 732,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.55,
                        "y": 0.241,
                        "w": 0.127,
                        "h": 0.356
                    }
                },
                {
                    "frame_index": 744,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.558,
                        "y": 0.248,
                        "w": 0.134,
                        "h": 0.343
                    }
                },
                {
                    "frame_index": 756,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.53,
                        "y": 0.224,
                        "w": 0.147,
                        "h": 0.365
                    }
                },
                {
                    "frame_index": 768,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.492,
                        "y": 0.183,
                        "w": 0.159,
                        "h": 0.38
                    }
                },
                {
                    "frame_index": 780,
                    "type": "face_bbox",
                    "data": {
                        "x": 0.457,
                        "y": 0.172,
                        "w": 0.152,
                        "h": 0.365
                    }
                }
            ]
        }
    ]
}

Dataset Management

/Datasets

GET /datasets/

Retrieve a list of Datset objects.

Returns: Pagination object with list of Dataset objects

URL Parameters:

offset - The index of the first object in the list to be returned, starting with 0 (default: 0)

limit - A limit on the number of objects to be returned (default: 10)

See Pagination and Filter for more information.

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/datasets/
# coming soon

Example response:

{
    "total": 8,
    "offset": 0,
    "limit": 3,
    "next": "http://api.deepva.com/api/v1/datasets/?limit=10&offset=10",
    "prev": "http://api.deepva.com/api/v1/datasets/?limit=10&offset=0",
    "data": [
        {
            "id": "015308de-f432-430b-b659-208e16fd5559",
            "name": "Demo",
            "description": "This is a dataset",
            "type": "face",
            "time_created": "2020-02-06 17:35:46.955000",
            "time_updated": "2020-02-06 17:35:46.955000",
            "number_of_classes": 25,
            "number_of_active_classes": 25,
            "number_of_images": 144,
            "number_of_active_images": 144,
            "preview_images": [
                "storage://0jmGBdonP9fBQjDdCoDi",
                "storage://vcK8yLNYMUoWVW3IfnGS",
                "storage://2x2Oeim8Ur3YzURmLSoU"
            ],
            "evaluation_result": {}
        },
        {
            "id": "1db75c6b-0767-4e2f-93d1-dca58f25e588",
            "name": "Test",
            "description": "This is a test dataset",
            "type": "face",
            "time_created": "2020-03-29 14:19:30.059000",
            "time_updated": "2020-03-29 14:19:30.059000",
            "number_of_classes": 7,
            "number_of_active_classes": 7,
            "number_of_images": 26,
            "number_of_active_images": 26,
            "preview_images": [
                "storage://Xm88Y6BNjRHX5IeofeeO",
                "storage://OeidQke7tgLzY5yDHC7Z",
                "storage://3Qgifdu7dYxAFcDoiTQd"
            ],
            "evaluation_result": {}
        },
        {
            "id": "d9e5e1ae-23e8-4d41-b11a-46558776a139",
            "name": "My Dataset",
            "description": "This is a dataset",
            "type": "face",
            "time_created": "2020-03-31 05:47:01.513000",
            "time_updated": "2020-03-31 05:47:01.513000",
            "number_of_classes": 3,
            "number_of_active_classes": 3,
            "number_of_images": 13,
            "number_of_active_images": 13,
            "preview_images": [
                "storage://mvbBcUz84a7RhahdFtU2",
                "storage://ctIbUq0XZzs38aiU6ITR",
                "storage://owWSFFjz5upPliDNd5GP"
            ],
            "evaluation_result": {}
        }
    ]
}
GET /datasets/{DATASET_ID}/

Retrieves a single Dataset object by its ID

Returns: Dataset object

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/datasets/{dataset_id}/
# coming soon

Example response:

{
    "id": "8dadd217-334f-4b45-9208-202310cedf68",
    "name": "My New Dataset",
    "description": "This is a dataset",
    "type": "face",
    "time_created": "2020-08-14 17:49:46.896000",
    "time_updated": "2020-08-14 17:49:46.896000",
    "number_of_classes": 1,
    "number_of_active_classes": 1,
    "number_of_images": 0,
    "number_of_active_images": 0,
    "preview_images": [],
    "evaluation_result": {}
}
POST /datasets/

Creates a new Dataset

Returns: Dataset object that has been created

Example request:

curl -d '{"name": "My New Dataset", "description": "This is a dataset", "type": "face"}' -H "Content-Type: application/json" -H "Authorization: Key {your-api-key}" -X POST https://api.deepva.com/api/v1/datasets/
# coming soon

Example response:

{
    "id": "b30a68e4-1853-4e83-89fb-5d135415ead3",
    "name": "My New Dataset",
    "description": "This is a dataset",
    "type": "face",
    "time_created": "2020-08-26 08:23:21.303951",
    "time_updated": "2020-08-26 08:23:21.303959",
    "number_of_classes": 0,
    "number_of_active_classes": 0,
    "number_of_images": 0,
    "number_of_active_images": 0,
    "preview_images": [],
    "evaluation_result": {}
}
DELETE /datasets/{DATASET_ID}/

Deletes a Dataset

Returns: Message saying that the dataset has been deleted

Example request:

curl -H "Authorization: Key {your-api-key}" -X DELETE https://api.deepva.com/api/v1/datasets/{DATASET_ID}/
# coming soon

Example response:

{
    "message": "Dataset has been deleted"
}

/Classes

GET /datasets/{DATASET_ID}/classes/

Retrieve a list of Class objects.

Returns: Pagination object with list of Class objects

URL Parameters:

offset - The index of the first object in the list to be returned, starting with 0 (default: 0)

limit - A limit on the number of objects to be returned (default: 10)

See Pagination and Filter for more information.

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/datasets/{dataset_id}/classes/
# coming soon

Example response:

{
    "total": 1,
    "offset": 0,
    "limit": 10,
    "next": "http://api.deepva.com/api/v1/datasets/8dadd217-334f-4b45-9208-202310cedf68/classes/?limit=10&offset=10",
    "prev": "http://api.deepva.com/api/v1/datasets/8dadd217-334f-4b45-9208-202310cedf68/classes/?limit=10&offset=0",
    "data": [
        {
            "id": "ab6c8b9a-2946-475b-89c2-f94e94d3e7d1",
            "reference": "bc2c4033-7b16-4122-abf9-1d4907c4599d",
            "label": "John Doe",
            "preview_image": {
                "id": "feb5a6ca-7eb2-4151-87a6-760ba50dcdb0",
                "file_uri": "storage://jRsMJzpOkC3Yk59hKEIA",
                "time_created": "2020-08-14 18:06:35.556000",
                "time_updated": "2020-08-14 18:06:35.556000",
                "active": true,
                "notes": "",
                "issue": -1,
                "is_auto_generated": false,
                "evaluation_result": {}
            },
            "time_created": "2020-08-14 17:59:15.096000",
            "time_updated": "2020-08-14 18:06:35.558000",
            "issues": [],
            "number_of_images": 1,
            "active": true,
            "notes": "",
            "expiration_date": null,
            "custom_fields": [],
            "level": -1,
            "evaluation_result": {}
        }
    ]
}
GET /datasets/{DATASET_ID}/classes/{CLASS_ID}/

Retrieves a single Class object by its ID

Returns: Class object

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/datasets/{dataset_id}/classes/{class_id}/
# coming soon

Example response:

{
    "id": "ab6c8b9a-2946-475b-89c2-f94e94d3e7d1",
    "reference": "bc2c4033-7b16-4122-abf9-1d4907c4599d",
    "label": "John Doe",
    "preview_image": {
        "id": "feb5a6ca-7eb2-4151-87a6-760ba50dcdb0",
        "file_uri": "storage://jRsMJzpOkC3Yk59hKEIA",
        "time_created": "2020-08-14 18:06:35.556000",
        "time_updated": "2020-08-14 18:06:35.556000",
        "active": true,
        "notes": "",
        "issue": -1,
        "is_auto_generated": false,
        "evaluation_result": {}
    },
    "time_created": "2020-08-14 17:59:15.096000",
    "time_updated": "2020-08-14 18:06:35.558000",
    "issues": [],
    "number_of_images": 1,
    "active": true,
    "notes": "",
    "expiration_date": null,
    "custom_fields": [],
    "level": -1,
    "evaluation_result": {}
}
POST /datasets/{DATASET_ID}/classes/

Creates a new Class

Returns: Class object that has been created

Example request:

curl -d '{"label": "John Doe"}' -H "Content-Type: application/json" -H "Authorization: Key {your-api-key}" -X POST https://api.deepva.com/api/v1/datasets/{dataset_id}/classes/
# coming soon

Example response:

{
    "id": "ab6c8b9a-2946-475b-89c2-f94e94d3e7d1",
    "reference": "bc2c4033-7b16-4122-abf9-1d4907c4599d",
    "label": "John Doe",
    "preview_image": null,
    "time_created": "2020-08-14 17:59:15.096000",
    "time_updated": "2020-08-14 17:59:15.096000",
    "issues": [],
    "number_of_images": 1,
    "active": true,
    "notes": "",
    "expiration_date": null,
    "custom_fields": [],
    "level": -1,
    "evaluation_result": {}
}
DELETE /datasets/{DATASET_ID}/classes/{CLASS_ID}/

Deletes a Class

Returns: Message saying that the class has been deleted

Example request:

curl -H "Authorization: Key {your-api-key}" -X DELETE https://api.deepva.com/api/v1/datasets/{DATASET_ID}/classes/{CLASS_ID}/
# coming soon

Example response:

{
    "message": "Class has been deleted"
}

Clustering

GET /datasets/{DATASET_ID}/classes/{CLASS_ID}/clusters/

Retrieve a list of Cluster objects. Clusters are available when Dataset Evaluation was triggered.

Returns: Pagination object with list of Cluster objects

URL Parameters:

offset - The index of the first object in the list to be returned, starting with 0 (default: 0)

limit - A limit on the number of objects to be returned (default: 10)

See Pagination and Filter for more information.

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/datasets/{dataset_id}/classes/{class_id}/clusters/
# coming soon

Example response:

{
    "total": 3,
    "offset": 0,
    "limit": 10,
    "next": "http://api.deepva.com/api/v1/datasets/9538e44c-6f30-40b7-8d7c-73bda1d41a9e/class/3d08d7c2-6e15-4a48-9cbd-c04dc257b4f8/clusters/?limit=5&offset=10",
    "prev": "http://api.deepva.com/api/v1/datasets/9538e44c-6f30-40b7-8d7c-73bda1d41a9e/class/3d08d7c2-6e15-4a48-9cbd-c04dc257b4f8/clusters/?limit=5&offset=0",
    "data": [
        {
            "name": "cluster_main",
            "preview_images":[
              "storage://V4Ic75h6RYqKXK9TkkDw",
              "storage://t7r2deRbEW8SxZy3oHyX",
              "storage://IQuHT85doYr8jZOV3AkJ",
              "storage://2n4pDh30LdyOOwhe0qyW"
           ]
        },
        {
            "name": "cluster_1",
            "preview_images":[
              "storage://n5etIg75HHrU10smd6iF",
              "storage://0tuoONKriUE9FYTnHFz9",
              "storage://D22PZOps8OrXUbWA0IYh",
              "storage://7gmS7dDLsf4EDhPiJYoS"
           ]
        },
        {
            "name": "outlier",
            "preview_images":[
              "storage://v6oPWj4NYhEWTKBRnMnc"
           ]
        }
    ]
}
GET /datasets/{DATASET_ID}/classes/{CLASS_ID}/clusters/{CLUSTER_NAME}/

Retrieves a single Cluster object by its cluster name.

Returns: Cluster object

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/datasets/{dataset_id}/classes/{class_id}/clusters/cluster_main/
# coming soon

Example response:

{
    "name": "cluster_main",
    "preview_images":[
      "storage://V4Ic75h6RYqKXK9TkkDw",
      "storage://t7r2deRbEW8SxZy3oHyX",
      "storage://IQuHT85doYr8jZOV3AkJ",
      "storage://2n4pDh30LdyOOwhe0qyW"
   ]
}
GET /datasets/{DATASET_ID}/classes/{CLASS_ID}/clusters/{CLUSTER_NAME}/images/

Retrieve a list of Image objects by a cluster name (all images that belongs to that cluster).

Returns: Pagination object with list of Image objects

URL Parameters:

offset - The index of the first object in the list to be returned, starting with 0 (default: 0)

limit - A limit on the number of objects to be returned (default: 10)

See Pagination and Filter for more information.

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/datasets/{dataset_id}/classes/{class_id}/clusters/cluster_main/images/
# coming soon

Example response:

{
    "total": 2,
    "offset": 0,
    "limit": 10,
    "next": "http://api.deepva.com/api/v1/datasets/9538e44c-6f30-40b7-8d7c-73bda1d41a9e/class/3d08d7c2-6e15-4a48-9cbd-c04dc257b4f8/clusters/cluster_main/images/?limit=5&offset=10",
    "prev": "http://api.deepva.com/api/v1/datasets/9538e44c-6f30-40b7-8d7c-73bda1d41a9e/class/3d08d7c2-6e15-4a48-9cbd-c04dc257b4f8/clusters/cluster_main/images/?limit=5&offset=0",
    "data": [
        {
          "id": "0a98ca4b-6c88-42e8-99d6-24d273f21e23",
          "file_uri": "storage://V4Ic75h6RYqKXK9TkkDw",
          "time_created": "2020-01-01 00:00:00.786000",
          "time_updated": "2020-01-01 00:00:00.786000",
          "active": true,
          "notes": "This is a text",
          "is_auto_generated": false,
          "evaluation_result": {
            "face_attributes": {
              "emotion": "Calm",
              "smile": false,
              "eyeglasses": false,
              "sunglasses": false,
              "eyesopen": true,
              "mouthopen": false,
              "beard": false,
              "mustache": false,
              "roll": -15,
              "yaw": 35.97,
              "pitch": -8.71
            },
            "face_clustering": "cluster_main"
          }
        },
        {
          "id": "1198ca4b-6c88-42e8-99d6-24d273f21e31",
          "file_uri": "storage://t7r2deRbEW8SxZy3oHyX",
          "time_created": "2020-01-01 00:00:00.786000",
          "time_updated": "2020-01-01 00:00:00.786000",
          "active": true,
          "notes": "",
          "is_auto_generated": false,
          "evaluation_result": {
            "face_attributes": {
              "emotion": "Calm",
              "smile": false,
              "eyeglasses": false,
              "sunglasses": false,
              "eyesopen": true,
              "mouthopen": false,
              "beard": false,
              "mustache": false,
              "roll": 30,
              "yaw": 25.30,
              "pitch": 2.31
            },
            "face_clustering": "cluster_main"
          }
        }
    ]
}

/Images

GET /datasets/{DATASET_ID}/classes/{CLASS_ID}/images/

Retrieve a list of Image objects.

Returns: Pagination object with list of Image objects

URL Parameters:

offset - The index of the first object in the list to be returned, starting with 0 (default: 0)

limit - A limit on the number of objects to be returned (default: 10)

See Pagination and Filter for more information.

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/datasets/{dataset_id}/classes/{image_id}/images/
# coming soon

Example response:

{
    "total": 1,
    "offset": 0,
    "limit": 10,
    "next": "http://api.deepva.com/api/v1/datasets/9006d642-db4c-48fd-8869-5f5a5f8e1419/classes/c47cc3ba-a49f-4304-b331-58444d306d58/images/?limit=10&offset=10",
    "prev": "http://api.deepva.com/api/v1/datasets/9006d642-db4c-48fd-8869-5f5a5f8e1419/classes/c47cc3ba-a49f-4304-b331-58444d306d58/images/?limit=10&offset=0",
    "data": [
        {
            "id": "12c5d48f-3a4a-45cc-959d-a19566ca4773",
            "file_uri": "storage://6fJYINhjbPBhvpuyCXxZ",
            "time_created": "2020-08-26 08:32:41.535000",
            "time_updated": "2020-08-26 08:32:41.535000",
            "active": true,
            "notes": "",
            "is_auto_generated": false,
            "evaluation_result": {}
        }
    ]
}
GET /datasets/{DATASET_ID}/classes/{CLASS_ID}/images/{IMAGE_ID}/

Retrieves a single Image object by its ID

Returns: Image object

Example request:

curl -v -H "Authorization: Key {your-api-key}" https://api.deepva.com/api/v1/datasets/{dataset_id}/classes/{class_id}/images/{image_id}/
# coming soon

Example response:

{
    "total": 1,
    "offset": 0,
    "limit": 10,
    "next": "http://api.deepva.com/api/v1/datasets/9006d642-db4c-48fd-8869-5f5a5f8e1419/classes/c47cc3ba-a49f-4304-b331-58444d306d58/images/?limit=10&offset=10",
    "prev": "http://api.deepva.com/api/v1/datasets/9006d642-db4c-48fd-8869-5f5a5f8e1419/classes/c47cc3ba-a49f-4304-b331-58444d306d58/images/?limit=10&offset=0",
    "data": [
        {
            "id": "12c5d48f-3a4a-45cc-959d-a19566ca4773",
            "file_uri": "storage://6fJYINhjbPBhvpuyCXxZ",
            "time_created": "2020-08-26 08:32:41.535000",
            "time_updated": "2020-08-26 08:32:41.535000",
            "active": true,
            "notes": "",
            "is_auto_generated": false,
            "evaluation_result": {}
        }
    ]
}
POST /datasets/{DATASET_ID}/classes/{CLASS_ID}/images/

Creates a new Image

Returns: Image object that has been created

Example request:

curl -d '{"file_uri": "storage://6fJYINhjbPBhvpuyCXxZ"}' -H "Content-Type: application/json" -H "Authorization: Key {your-api-key}" -X POST https://api.deepva.com/api/v1/datasets/{dataset_id}/classes/{class_id}/images/
# coming soon

Example response:

{
    "id": "12c5d48f-3a4a-45cc-959d-a19566ca4773",
    "file_uri": "storage://6fJYINhjbPBhvpuyCXxZ",
    "time_created": "2020-08-26 08:32:41.535313",
    "time_updated": "2020-08-26 08:32:41.535322",
    "active": true,
    "notes": "",
    "is_auto_generated": false,
    "evaluation_result": {}
}
DELETE /datasets/{DATASET_ID}/classes/{CLASS_ID}/images/{IMAGE_ID}/

Deletes an Image

Returns: Message saying that the image has been deleted

Example request:

curl -H "Authorization: Key {your-api-key}" -X DELETE https://api.deepva.com/api/v1/datasets/{DATASET_ID}/classes/{CLASS_ID}/{CLASS_ID}/images/{IMAGE_ID}/
# coming soon

Example response:

{
    "message": "Image has been deleted"
}

Custom Training and Models

/Trainings

POST /trainings/

Creates a new Training

Returns: Training object that has been created

Example request:

curl -d '{ "source_dataset_id": "b97e20c8-3e68-4831-8eaf-e7a592d3a802", "output_model_name": "My Model", "output_model_description": "This is a model which training was started via Postman", "output_model_changelog": "initial training", "config": {} }' -H "Content-Type: application/json" -H "Authorization: Key {your-api-key}" -X POST https://api.deepva.com/api/v1/trainings/
# coming soon

Example response:

{
    "id": "174f8cd7-64a1-4b0c-8735-cbbc80d24024",
    "type": "face",
    "state": "waiting",
    "progress": 0,
    "duration": 0,
    "error": "",
    "time_created": "2020-12-15 11:39:22.792673",
    "time_started": null,
    "time_completed": null,
    "source_dataset": {
        "id": "b97e20c8-3e68-4831-8eaf-e7a592d3a802",
        "name": "Test",
        "description": "A test dataset",
        "version": 1.0,
        "type": "face",
        "time_created": "2020-10-30 17:34:41.480000",
        "time_updated": "2020-10-30 17:34:41.480000",
        "number_of_classes": 0,
        "number_of_active_classes": 0,
        "number_of_images": 0,
        "number_of_active_images": 0,
        "preview_images": [],
        "evaluation_result": {
            "gender_statistics": {
                "male": 5
            }
        },
        "evaluation_state": 0,
        "issues": {
            "has_error": true,
            "has_warning": false
        }
    },
    "output_model_name": "My Model",
    "output_model": null,
    "config": {},
    "output_model_description": "This is a model which training was started via Postman",
    "output_model_changelog": "initial training"
}

The Training has just been created. The state is "waiting" becasue it waits for processing by DeepVA. As soon as the job is done (state = "completed") you will see your new custom trained model at https://api.deepva.com/api/v1/models/ (models endpoint).

You can request the Training by its ID and check the state: https://api.deepva.com/v1/trainings/174f8cd7-64a1-4b0c-8735-cbbc80d24024/

/Models

/Storage

Postman File

If you want to test our API with the handy tool Postman, you can download a Postman project here and import it in Postman:

DeepVA API.postman_collection.json (updated 26. Aug 2020, 14:48)

Using Postman for easy testing our REST-API