🟢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

post

Create a new subject

Authorizations

Path parameters

company_idstring · uuidRequired

dataset_idstring · uuidRequired

Body

Serializer to get dataset id from urls.

namestring · min: 1 · max: 512Required

birth_datestring | nullOptional

subject birth date

biological_sexstring | null · min: 1Optional

subject biological sex id

metaone ofOptional

subject meta data

anyOptional

nullOptional

Responses

201Success

application/json

400Error

application/json

post

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

POST /api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "name": "text",
  "birth_date": null,
  "biological_sex": null,
  "meta": null
}

{
  "name": "text",
  "birth_date": null,
  "biological_sex": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "tech_name": "text"
  },
  "meta": null,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "author_id": null,
  "creation_time": "2025-10-29T02:34:24.440Z",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "dataset": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "promote_image_id": null
}

Update subject

patch

Update subject

Authorizations

Path parameters

company_idstring · uuidRequired

dataset_idstring · uuidRequired

subject_idstring · uuidRequired

Body

namestring · min: 1 · max: 512Optional

birth_datestring | nullOptional

biological_sexstring | nullOptional

metaone ofOptional

anyOptional

nullOptional

Responses

200Success

application/json

400Error

application/json

patch

/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/

PATCH /api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "name": "text",
  "birth_date": null,
  "biological_sex": null,
  "meta": null
}

{
  "name": "text",
  "birth_date": null,
  "biological_sex": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "tech_name": "text"
  },
  "meta": null,
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "author_id": null,
  "creation_time": "2025-10-29T02:34:24.440Z",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "dataset": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "promote_image_id": null
}

List subjects in dataset

List subjects

get

List subjects

Authorizations

Path parameters

company_idstring · uuidRequired

dataset_idstring · uuidRequired

Query parameters

qstringOptional

A search term.

pageintegerOptional

A page number within the paginated result set.

page_sizeintegerOptional

Number of results to return per page.

namestringOptional

Responses

200Success

application/json

get

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

GET /api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "name": "text",
      "birth_date": null,
      "biological_sex": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "tech_name": "text"
      },
      "meta": null,
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "author_id": null,
      "creation_time": "2025-10-29T02:34:24.440Z",
      "company": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "dataset": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "promote_image_id": null
    }
  ]
}

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

Delete subject

Authorizations

Path parameters

company_idstring · uuidRequired

dataset_idstring · uuidRequired

subject_idstring · uuidRequired

Responses

204

No response body

No content

delete

/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/

DELETE /api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

204

No response body

No content

Delete multiple subjects

Delete subjects in batch (multiple subjects in one request)

delete

Delete multiple subjects in one request

Authorizations

Path parameters

company_idstring · uuidRequired

dataset_idstring · uuidRequired

Query parameters

subjects_idsstring · uuid[]Required

Responses

200Success

application/json

delete

/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/delete/

DELETE /api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/delete/?subjects_ids=123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

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

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

delete

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

Authorizations

Path parameters

company_idstring · uuidRequired

dataset_idstring · uuidRequired

subject_idstring · uuidRequired

Responses

200Success

application/json

delete

/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/storage/

DELETE /api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/storage/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

{
  "status": "text"
}

Clear subject metadata

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

delete

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

Authorizations

Path parameters

company_idstring · uuidRequired

dataset_idstring · uuidRequired

subject_idstring · uuidRequired

Responses

200Success

application/json

delete

/api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/metadata/

DELETE /api/v1/companies/{company_id}/datasets/{dataset_id}/subjects/{subject_id}/metadata/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

{
  "status": "text"
}

PreviousHair Volume NextAPI for Images

Last updated 11 months ago

Was this helpful?

What can you do?

Create subject

Create subject

Update subject

Update subject

List subjects in dataset

List subjects

Delete subject

Delete a subject

Delete subject

Delete multiple subjects

Delete subjects in batch (multiple subjects in one request)

Clear subject's data (GDPR-related actions)

Delete photos from storage

Clear images from storage for subject

Clear subject metadata

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