🟢API for Subjects

This page contains description of subjects management via API.

A SaaS Subject is a unique end-user (person) that uses your application powered by Haut.AI technology, e.g., one of your customers or one of your study participants.

What is subject?

What can you do?

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

• Create subject

• Update subject

• List dataset subjects

• Delete subject(s)

• Clear subject's data (GDPR-related actions)

---

Create subject

Create a subject connected to your user (e.g. the user user1 connects to your app, you create a subject with the name user1, so you can easily find all the images of this user), uniqueness of the subject is not required, but it's recommended to use unique subjects' names to identify users and their images along with results later easily.

Every subject has an internal id ID in SaaS (it looks like this 2fea742a-62ec-4a81-9729-9e0283f9c40c), it's a good practice to have a mapping of our IDs to users within your app or platform.

Create subject

Create a new subject

POSThttps://saas.haut.ai/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

dataset_id*string (uuid)

Body

application/json

name*string

birth_datestring,null (date)

subject birth date

biological_sexstringnull

subject biological sex id

metaone of

subject meta data

anynull

Response

201400

Body

application/json

name*string

birth_datestring,null (date)

subject birth date

biological_sexone of

subject biological sex id

SubjectBiologicalSexOut (object)null

metaone of

subject meta data

anynull

id*string (uuid)

author_id*integernull

creation_time*string (date-time)

subject creation date

company*all of

subject company data

dataset*all of

subject company data

promote_image_idstring,null (uuid)

promote image identifier

Request

JavaScriptCurlPython

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

Response

201400

{
  "name": "text",
  "biological_sex": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "tech_name": "text"
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "creation_time": "2024-12-21T16:11:41.137Z",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "dataset": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  }
}

---

Update subject

Update subject

Update subject

PATCHhttps://saas.haut.ai/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

dataset_id*string (uuid)

subject_id*string (uuid)

Body

application/json

namestring

birth_datestring,null (date)

biological_sexstring,null (uuid)

metaone of

anynull

Response

200400

Body

application/json

name*string

birth_datestring,null (date)

subject birth date

biological_sexone of

subject biological sex id

SubjectBiologicalSexOut (object)null

metaone of

subject meta data

anynull

id*string (uuid)

author_id*integernull

creation_time*string (date-time)

subject creation date

company*all of

subject company data

dataset*all of

subject company data

promote_image_idstring,null (uuid)

promote image identifier

Request

JavaScriptCurlPython

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

Response

200400

{
  "name": "text",
  "biological_sex": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "tech_name": "text"
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "creation_time": "2024-12-21T16:11:41.137Z",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "dataset": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  }
}

---

List subjects in dataset

List subjects

List subjects

GEThttps://saas.haut.ai/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

dataset_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 ItemSubjectOut (object)

Request

JavaScriptCurlPython

const response = await fetch('https://saas.haut.ai/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/', {
    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": [
    {
      "name": "text",
      "biological_sex": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "tech_name": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "creation_time": "2024-12-21T16:11:41.137Z",
      "company": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "dataset": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      }
    }
  ]
}

---

Delete subject

If you delete a subject, you won't be able to upload images to it anymore. You must recreate subject to do it. Otherwise you would get an API error.

Delete a subject

Delete subject

Delete subject

DELETEhttps://saas.haut.ai/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

dataset_id*string (uuid)

subject_id*string (uuid)

Response

204

No response body

Request

JavaScriptCurlPython

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

Delete multiple subjects

Delete subjects in batch (multiple subjects in one request)

Delete multiple subjects in one request

DELETEhttps://saas.haut.ai/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/delete/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

dataset_id*string (uuid)

Query parameters

Response

200

Body

application/json

deleted*array of string (uuid)

Request

JavaScriptCurlPython

const response = await fetch('https://saas.haut.ai/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/delete/?subjects_ids=123e4567-e89b-12d3-a456-426614174000', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200

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

---

Clear subject's data (GDPR-related actions)

Delete photos from storage

There are 2 types of objects in SaaS platform: Image file in Storage and Image record in Database.

Image file is the original image, uploaded by client - you - to SaaS platform.

Image record is a record in database, that contains links to:

• Image file in storage

• Associated objects like Metrics and Masks results and Aux Images

When you trigger "Delete photos from storage" action via API, SaaS deletes immediately Image files from Storage. But this action does not delete Image record, so all associated objects like Metrics and Masks results for this image and Aux Images for this image will NOT be deleted.

If Image file has been deleted, you will see "No photo" text on image, if you go to SaaS b2b Portal interface (SaaS > Datasets > Image) and open this image record.

Clear images from storage for subject

Clear images from storage for subject. This action will not delete images from database

DELETEhttps://saas.haut.ai/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/storage/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

dataset_id*string (uuid)

subject_id*string (uuid)

Response

200

Body

application/json

status*string

Request

JavaScriptCurlPython

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

Response

200

{
  "status": "text"
}

---

Clear subject metadata

Clear fields: meta , biological sex, birthdate, phenotype and metrics and submetrics for subject

Clear fields: meta , biological_sex, birthdate, phenotype and metrics and submetrics for subject

DELETEhttps://saas.haut.ai/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/metadata/

Authorization

PrivateTokenAuthPasswordAuthcookieAuth

Path parameters

company_id*string (uuid)

dataset_id*string (uuid)

subject_id*string (uuid)

Response

200

Body

application/json

status*string

Request

JavaScriptCurlPython

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

Response

200

{
  "status": "text"
}