> For the complete documentation index, see [llms.txt](https://docs.saas.haut.ai/haut.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saas.haut.ai/haut.ai/developers/saas-api-overview/api-for-subjects.md).

# 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?](/haut.ai/haut.ai-features/datasets/subjects.md)

## What can you do?

You can find more details on these actions in the **Subject section** of [Swagger](https://saas.haut.ai/api/swagger/#/Subjects).

* [Create subject](#create-subject)
* [Update subject](#update-subject)
* [List dataset subjects](#list-subjects)
* [Delete subject(s)](#delete-subject)
* [Clear subject's data](#gdpr-related-actions) (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.

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_id}/subjects/" method="post" %}
[openapi.json](https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FRF3DdAp7DPLxOGdzKdfj%2Fopenapi.json?alt=media\&token=805fe368-c61f-4e86-bf72-e2de9d7d6e61)
{% endopenapi %}

***

## Update subject

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_id}/subjects/{subject\_id}/" method="patch" %}
[openapi.json](https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FRF3DdAp7DPLxOGdzKdfj%2Fopenapi.json?alt=media\&token=805fe368-c61f-4e86-bf72-e2de9d7d6e61)
{% endopenapi %}

***

## List subjects in dataset

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_id}/subjects/" method="get" %}
[openapi.json](https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FRF3DdAp7DPLxOGdzKdfj%2Fopenapi.json?alt=media\&token=805fe368-c61f-4e86-bf72-e2de9d7d6e61)
{% endopenapi %}

***

## 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

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_id}/subjects/{subject\_id}/" method="delete" %}
[openapi.json](https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FRF3DdAp7DPLxOGdzKdfj%2Fopenapi.json?alt=media\&token=805fe368-c61f-4e86-bf72-e2de9d7d6e61)
{% endopenapi %}

### Delete multiple subjects

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_id}/subjects/delete/" method="delete" %}
[openapi.json](https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FRF3DdAp7DPLxOGdzKdfj%2Fopenapi.json?alt=media\&token=805fe368-c61f-4e86-bf72-e2de9d7d6e61)
{% endopenapi %}

***

## 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](/haut.ai/developers/saas-api-overview/api-for-metrics-and-submetrics.md) and [Masks](/haut.ai/developers/saas-api-overview/api-for-images/api-for-masks.md) results and [Aux Images](/haut.ai/developers/saas-api-overview/api-for-images/api-for-aux-images.md)

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.

{% hint style="info" %}
If Image file has been deleted, you will see "No photo" text on image, if you go to SaaS b2b Portal interface (SaaS > [Datasets](/haut.ai/haut.ai-features/datasets.md) > Image) and open this image record.
{% endhint %}

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_id}/subjects/{subject\_id}/storage/" method="delete" %}
[openapi.json](https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FRF3DdAp7DPLxOGdzKdfj%2Fopenapi.json?alt=media\&token=805fe368-c61f-4e86-bf72-e2de9d7d6e61)
{% endopenapi %}

***

### Clear subject metadata

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_id}/subjects/{subject\_id}/metadata/" method="delete" %}
[openapi.json](https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FRF3DdAp7DPLxOGdzKdfj%2Fopenapi.json?alt=media\&token=805fe368-c61f-4e86-bf72-e2de9d7d6e61)
{% endopenapi %}

***

{% hint style="warning" %}
Not a Haut.AI client yet?
{% endhint %}

<a href="https://haut.ai/book-a-demo?utm_source=referral&#x26;utm_medium=saas_docs&#x26;utm_campaign=Docs_SaaS_HautAI" class="button primary" data-icon="user-vneck">Book a demo</a> <a href="https://haut.ai/product/ai-skin-analysis?utm_source=referral&#x26;utm_medium=saas_docs&#x26;utm_campaign=Docs_SaaS_HautAI" class="button secondary" data-icon="external-link">Platform overview on haut.ai</a>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.saas.haut.ai/haut.ai/developers/saas-api-overview/api-for-subjects.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.