🟢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

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
or
nullOptional
Responses
201Success
application/json
post
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-08T20:00:33.223Z",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "dataset": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "promote_image_id": null
}

Update subject

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
or
nullOptional
Responses
200Success
application/json
patch
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-08T20:00:33.223Z",
  "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
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-08T20:00:33.223Z",
      "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
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
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"
  ]
}

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:

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
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
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 VolumeNextAPI for Images

Last updated

Was this helpful?