# Manage file storage

Create and maintain root volumes and files in a database, and inspect file artifacts. A volume belongs to a database; for tables and table data, see [Manage catalogs, databases, and tables](https://omnifabric.cloudsigma.com/docs/developer/api/ai-studio/workspace-resources/catalog-databases-tables.html.md).

In the console, the storage object available from the database plus button is a volume. In a volume file list, an item whose `file_type` is `folder` represents **Open folder**. See [List files](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/list-files.html.md).

## Prerequisites

- Prepare access to the target workspace. For general rules, see [Make your first AI Studio API call](https://omnifabric.cloudsigma.com/docs/developer/quickstart/index.html.md).
- Before creating a volume, determine its database.
- Before associating an uploaded file with a volume, obtain the file record created by upload and the target volume.

## Call sequence

1. Identify the target database in the Catalog hierarchy. When you need a new storage location, create a root volume in that database and retain its ID.
2. Use the volume ID to list files and confirm the location. To add a sublevel, create a folder in the volume or an existing folder. A `folder` item in the list remains under the same volume; retain `volume_id` and provide `parent_id` on the next query.
3. After uploading a file, use the create-file operation to associate its existing file record with the target volume. Then inspect file details or the file list to confirm. Confirm a folder's location before changing it.
4. Preview, download, or stream-read a file when you need to inspect its content. To inspect processing results for multiple files, batch-query file artifacts or data assets.
5. Before unlinking, emptying, or deleting, inspect target details and references. After deleting a volume, folder, or file, query available resources again to confirm the result.

## API operations

### Create and maintain volumes

| Task | Use it when |
| --- | --- |
| [Create a volume](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/create-volume.html.md) | You determined the target database and need a root volume. |
| [Get volume details](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/get-volume.html.md) | You need to confirm a target root volume's current information. |
| [Get a volume's full path](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/get-volume-path.html.md) | You need to confirm the volume's place in the Catalog hierarchy. |
| [Update a volume](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/update-volume.html.md) | You need to change a volume's name or description. |
| [Delete a volume](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/delete-volume.html.md) | You handled files in the volume and need to remove the root volume. |
| [List volume references](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/list-volume-references.html.md) | You need to inspect references before changing or deleting a volume. |

### Manage folders

| Task | Use it when |
| --- | --- |
| [Create a folder](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/create-folder.html.md) | You need to create a subfolder in a volume or existing folder. |
| [Update a folder](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/update-folder.html.md) | You need to change folder information. |
| [List folder references](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/list-folder-references.html.md) | You need to inspect references before changing, emptying, or deleting a folder. |
| [Empty a folder](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/empty-folder.html.md) | You need to remove content from the specified folder and its subfolders. |
| [Delete a folder](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/delete-folder.html.md) | You confirmed that the target folder is no longer needed. |

### Upload, associate, and access files

| Task | Use it when |
| --- | --- |
| [Upload a file](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/upload-file.html.md) | You first need to upload a file that is not associated with a volume. |
| [Create a file](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/create-file.html.md) | You need to associate an existing file record with a specified volume. |
| [List files](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/list-files.html.md) | You need to confirm files in a volume or open a folder item in the list. |
| [Get file details](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/get-file.html.md) | You need current file information or a target for a subsequent operation. |
| [Update a file](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/update-file.html.md) | You need to submit a file-update request. |
| [Preview a file](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/preview-file.html.md) | You need to inspect file content inline. |
| [Download a file](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/download-file.html.md) | You need to obtain file content. |
| [Unlink files](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/unlink-file.html.md) | You need to unlink a group of files in the same root volume. |
| [Delete a file](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/delete-file.html.md) | You confirmed that the target file is no longer needed. |
| [Trigger a file workflow](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/trigger-file-workflow.html.md) | You need to trigger the workflow associated with a file. |

### Inspect processing results

| Task | Use it when |
| --- | --- |
| [Query file artifacts](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/list-file-artifacts.html.md) | You need file-artifact information by file ID. |
| [Query a data asset](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/get-data-asset.html.md) | You need a processed data asset by original file ID. |
| [Batch-query file artifacts](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/batch-resolve-file-artifacts.html.md) | You need processing associations for multiple files in one query. |
| [Batch-query data assets](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/batch-get-data-assets.html.md) | You need data assets for multiple original files in one query. |

## Confirm the result

Use [volume details](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/get-volume.html.md), [file details](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/get-file.html.md), or [the file list](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/resource-center/catalog/list-files.html.md) to confirm creation, association, and updates. File artifacts and data assets are the source of truth for file processing results.

## Limitations and notes

- File lists must be filtered by exactly one `volume_id`; retain that `volume_id` when opening a folder item.
- Uploading a file does not automatically associate it with a volume; call the create-file operation afterwards.
- Unprocessed files do not appear in data-asset query results.
- Before deleting a volume, handle the files in it. A group of files to unlink must belong to the same root volume.
- The update-file API does not currently persist name changes. Do not treat a successful response as confirmation that the file name was updated.

## Next steps

- [Manage catalogs, databases, and tables](https://omnifabric.cloudsigma.com/docs/developer/api/ai-studio/workspace-resources/catalog-databases-tables.html.md)