> 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-datasets.md).

# API for Datasets

This page contains description of datasets management via API.

Datasets are spaces where you can store and manage your end-user data, such as images and metrics.

[What is dataset?](/haut.ai/haut.ai-features/datasets.md)

## What can you do

You can find more details on these actions in the **Dataset section** of [Swagger](http://localhost:8080/api/swagger/#/Datasets).

* [Create](#create-dataset)
* [List](#list-dataset)
* [Update](#update-dataset)
* [Delete](#delete-dataset)

## Create dataset

Please do not create a dataset for each analysis. Create a dataset for your app, your study, or something big.

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/" 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 %}

#### Optional Features for Dataset Creation

When creating a dataset, you can customize its behavior using several optional fields. These options give you control over how long images and their metadata are stored, as well as when to clean up images after processing.

#### Optional Fields:

1. **`expire_images_after_days`**:
   * Set this to any positive integer (including 0) to automatically delete uploaded images after the specified number of days.
   * **Default value:** images are not deleted at all.
   * **Example**: If set to `7`, images will be deleted 7 days after they are uploaded.
   * **Note:** if you visited UI and opened an image, it is cached in the browser for 24 hours, so you will still see it in UI even after auto-deletion.
2. **`expire_metadata_after_days`**:
   * This works similarly to `expire_images_after_days`, but applies to the **subject metadata (birth\_date, phenotype, biological\_sex, meta fields)** and **metrics and submetrics** stored in the dataset.
   * **Default value:** metadata is not deleted at all.
   * If set to any positive integer (including 0), the metadata and results will be cleared from the database after the specified number of days.
3. **`expire_survey_after_days`**:
   * Works the same way for **survey answers** collected by a Consumer App or study survey, including email addresses, phone numbers, and free text.
   * **Default value:** survey answers are not deleted at all.
4. **`clean_images_as_soon_as_ready`**:
   * If set to `true`, uploaded images will be scheduled for deletion 60 minutes after the algorithms finish processing. This helps to reduce storage usage by cleaning up images that are no longer needed immediately after processing.
   * **Default value:** images are not deleted at all.
   * **Note:** if you visited UI and opened an image, it is cached in the browser for 24 hours, so you will still see it in UI even after auto-deletion.

#### Use Cases:

* **Short-term storage**: If you're working with sensitive data or want to minimize storage costs, use `expire_images_after_days` and `clean_images_as_soon_as_ready` to ensure images are cleaned up quickly.\
  **Critical to notice:** if you need any help with understanding why image is processed "like that", with these settings our Support team can not help, as images are already deleted.
* **Long-term metadata retention**: You can still retain algorithm results and metadata for a longer period using `expire_metadata_after_days`, even after the images are deleted

The same three settings are available in the SaaS platform under the dataset's **Settings → General → Data retention**, where they can also be set in minutes or months. See [Data Retention](/haut.ai/haut.ai-features/datasets/data-retention.md).

***

## List datasets

Retrieve a list of all datasets associated with your company. This is useful for managing multiple datasets, keeping track of usage, and reviewing the status of stored data.

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/" 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 dataset

You can delete a dataset when it’s no longer needed. Deleting a dataset will remove all images, metadata, and metrics and submetrics stored within it.

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_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 %}

***

## Update dataset

Certain fields in a dataset can be modified after creation. This allows you to update key attributes like the dataset's name or adjust optional features such as expiration settings (`expire_images_after_days`, `expire_metadata_after_days`, etc.).

{% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_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 %}

***

{% 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-datasets.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.