🟢API for Datasets

This page contains description of datasets management via API.

Datasets are spaces where you can store and manage your end-user data, such as images and metrics.

What is dataset?

What can you do

You can find more details on these actions in the Dataset section of Swagger.

• Create

• List

• Update

• Delete

Create dataset

Please do not create a dataset for each analysis. Create a dataset for your app, your study, or something big.

Create dataset

Create a new dataset

POST/api/v1/companies/{company_id}/datasets/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

Body

application/json

name*string

image_type_idintegernull

dataset image type id, you can find all available image types in /dicts/image_types/ API method

expire_images_after_daysintegernull

expire_metadata_after_daysintegernull

clean_images_as_soon_as_readyboolean

custom_brandingintegernull

Response

201400409

Body

application/json

id*string (uuid)

company_id*string (uuid)

dataset company id

name*string

dataset name

image_type*ImageTypeOut (object)

image_type_name*string

image_type_tech_name*string

connected_applications*array of object

expire_images_after_daysintegernull

expire_metadata_after_daysintegernull

clean_images_as_soon_as_readyboolean

algorithms_bucketing*array of AlgorithmsBucket (object)

custom_branding*one of

CustomBranding (object)null

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/companies/{company_id}/datasets/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text"
    }),
});
const data = await response.json();

Response

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "company_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "image_type": {
    "name": "text",
    "tech_name": "text",
    "sides": [
      {
        "name": "text",
        "tech_name": "text"
      }
    ],
    "lights": [
      {
        "name": "text",
        "tech_name": "text"
      }
    ]
  },
  "image_type_name": "text",
  "image_type_tech_name": "text",
  "connected_applications": [],
  "clean_images_as_soon_as_ready": false,
  "algorithms_bucketing": [
    {}
  ],
  "custom_branding": {
    "name": "text"
  }
}

Optional Features for Dataset Creation

When creating a dataset, you can customize its behavior using several optional fields. These options give you control over how long images and their metadata are stored, as well as when to clean up images after processing.

Optional Fields:

1. expire_images_after_days:

   • Set this to any positive integer (including 0) to automatically delete uploaded images after the specified number of days.

   • Default value: images are not deleted at all.

   • Example: If set to 7, images will be deleted 7 days after they are uploaded.

   • Note: if you visited UI and opened an image, it is cached in the browser for 24 hours, so you will still see it in UI even after auto-deletion.

2. expire_metadata_after_days:

   • This works similarly to expire_images_after_days, but applies to the subject metadata (birth_date, phenotype, biological_sex, meta fields) and metrics and submetrics stored in the dataset.

   • Default value: metadata is not deleted at all.

   • If set to any positive integer (including 0), the metadata and results will be cleared from the database after the specified number of days.

3. clean_images_as_soon_as_ready:

   • If set to true, uploaded images will be scheduled for deletion 15 minutes after the algorithms finish processing. This helps to reduce storage usage by cleaning up images that are no longer needed immediately after processing.

   • Default value: images are not deleted at all.

   • Note: if you visited UI and opened an image, it is cached in the browser for 24 hours, so you will still see it in UI even after auto-deletion.

Use Cases:

• Short-term storage: If you're working with sensitive data or want to minimize storage costs, use expire_images_after_days and clean_images_as_soon_as_ready to ensure images are cleaned up quickly. Critical to notice: if you need any help with understanding why image is processed "like that", with these settings our Support team can not help, as images are already deleted.

• Long-term metadata retention: You can still retain algorithm results and metadata for a longer period using expire_metadata_after_days, even after the images are deleted

---

List dataset

Retrieve a list of all datasets associated with your company. This is useful for managing multiple datasets, keeping track of usage, and reviewing the status of stored data.

Get datasets list

GET/api/v1/companies/{company_id}/datasets/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

Query parameters

Response

200

Body

application/json

count*integer

Example: 123

nextnullable string (uri)

Example: "http://api.example.org/accounts/?page=4"

previousnullable string (uri)

Example: "http://api.example.org/accounts/?page=2"

results*array of ItemDatasetList (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/companies/{company_id}/datasets/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "company_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "image_type": {
        "name": "text",
        "tech_name": "text",
        "sides": [
          {
            "name": "text",
            "tech_name": "text"
          }
        ],
        "lights": [
          {
            "name": "text",
            "tech_name": "text"
          }
        ]
      },
      "image_type_name": "text",
      "image_type_tech_name": "text",
      "connected_applications": [],
      "author": {
        "email": "[e-mail]",
        "username": "[e-mail]"
      },
      "creation_time": "2024-10-22T10:50:16.565Z"
    }
  ]
}

---

Delete dataset

You can delete a dataset when it’s no longer needed. Deleting a dataset will remove all images, metadata, and metrics and submetrics stored within it.

Delete dataset

DELETE/api/v1/companies/{company_id}/datasets/{dataset_id}/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

dataset_id*string (uuid)

Response

200404

Body

application/json

deleted*string (uuid)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/companies/{company_id}/datasets/{dataset_id}/', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200

{
  "deleted": "123e4567-e89b-12d3-a456-426614174000"
}

---

Update dataset

Certain fields in a dataset can be modified after creation. This allows you to update key attributes like the dataset's name or adjust optional features such as expiration settings (expire_images_after_days, expire_metadata_after_days, etc.).

Update dataset

PATCH/api/v1/companies/{company_id}/datasets/{dataset_id}/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

dataset_id*string (uuid)

Body

application/json

namestring

custom_brandingintegernull

expire_images_after_daysintegernull

expire_metadata_after_daysintegernull

clean_images_as_soon_as_readyboolean

Response

200400

Body

application/json

id*string (uuid)

company_id*string (uuid)

dataset company id

name*string

dataset name

image_type*ImageTypeOut (object)

image_type_name*string

image_type_tech_name*string

connected_applications*array of object

expire_images_after_daysintegernull

expire_metadata_after_daysintegernull

clean_images_as_soon_as_readyboolean

algorithms_bucketing*array of AlgorithmsBucket (object)

custom_branding*one of

CustomBranding (object)null

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/companies/{company_id}/datasets/{dataset_id}/', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "company_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "image_type": {
    "name": "text",
    "tech_name": "text",
    "sides": [
      {
        "name": "text",
        "tech_name": "text"
      }
    ],
    "lights": [
      {
        "name": "text",
        "tech_name": "text"
      }
    ]
  },
  "image_type_name": "text",
  "image_type_tech_name": "text",
  "connected_applications": [],
  "clean_images_as_soon_as_ready": false,
  "algorithms_bucketing": [
    {}
  ],
  "custom_branding": {
    "name": "text"
  }
}