🟢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

POST/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

201400409

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('/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

201

{
  "name": "text",
  "biological_sex": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "tech_name": "text"
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "creation_time": "2024-10-22T10:28:31.019Z",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "dataset": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  }
}

---

Update subject

Update subject

Update subject

PATCH/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('/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-10-22T10:28:31.019Z",
  "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

GET/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('/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-10-22T10:28:31.019Z",
      "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

DELETE/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('/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

DELETE/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('/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

Clear images from storage for subject

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

DELETE/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('/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

DELETE/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('/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"
}