# 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](catalog-databases-tables.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](../../../../reference/api/ai-studio/resource-center/catalog/list-files.md).

## Prerequisites

- Prepare access to the target workspace. For general rules, see [Prepare to call an API](../../api-call-basics.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

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

### Manage folders

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

### Upload, associate, and access files

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

### Inspect processing results

| What you need to do | API operation | Use it when |
| --- | --- | --- |
| Query file artifacts | [List file artifacts](../../../../reference/api/ai-studio/resource-center/catalog/list-file-artifacts.md) | You need file-artifact information by file ID. |
| Query a data asset | [Get a data asset](../../../../reference/api/ai-studio/resource-center/catalog/get-data-asset.md) | You need a processed data asset by original file ID. |
| Batch-query file artifacts | [Batch-resolve file artifacts](../../../../reference/api/ai-studio/resource-center/catalog/batch-resolve-file-artifacts.md) | You need processing associations for multiple files in one query. |
| Batch-query data assets | [Batch-get data assets](../../../../reference/api/ai-studio/resource-center/catalog/batch-get-data-assets.md) | You need data assets for multiple original files in one query. |

## Confirm the result

Use [volume details](../../../../reference/api/ai-studio/resource-center/catalog/get-volume.md), [file details](../../../../reference/api/ai-studio/resource-center/catalog/get-file.md), or [the file list](../../../../reference/api/ai-studio/resource-center/catalog/list-files.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](catalog-databases-tables.md)