> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/developers/files-and-assets/files-and-folders.md).

# Files & folders

Move, copy, rename, trash, and delete files and folders, and create folders.

Paths start with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`. Renaming is a move to a new path in the same folder.

* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be restored from the drive's trash, but deleted files can't.
* The `/batch` variants take a list of paths in one request.

To upload files, use the [S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the [file system API](https://academy.shade.inc/developers/writing-your-own-uploader). `GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file system API needs.

## POST /files/directory

> Ensure a directory exists at the given path, creating if needed

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"CreateFolderRequest":{"properties":{"path":{"type":"string","format":"path","title":"The path to ensure a directory for","description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive we want to make a directory in"}},"type":"object","required":["path","drive_id"],"title":"CreateFolderRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/directory":{"post":{"tags":["files"],"summary":"Ensure a directory exists at the given path, creating if needed","operationId":"createFolder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFolderRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /files/directory/batch

> Ensure a list of directories exist at the given path, creating if needed

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"CreateFoldersRequest":{"properties":{"paths":{"items":{"type":"string","format":"path"},"type":"array","title":"The paths to ensure directories for","description":"The paths to ensure directories exist at"},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive we want to make a directory in"}},"type":"object","required":["paths","drive_id"],"title":"CreateFoldersRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/directory/batch":{"post":{"tags":["files"],"summary":"Ensure a list of directories exist at the given path, creating if needed","operationId":"createFolders","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFoldersRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Move a file or folder to a new location

> Move a file or folder to a new location

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"MoveFileRequest":{"properties":{"source":{"type":"string","format":"path","title":"The source path","description":"Current path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},"destination":{"type":"string","format":"path","title":"The destination path","description":"New path for the file or folder, starting with the drive ID. To rename, keep the same folder and change the name."},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing the file to move"}},"type":"object","required":["source","destination","drive_id"],"title":"MoveFileRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/move":{"post":{"tags":["files"],"summary":"Move a file or folder to a new location","description":"Move a file or folder to a new location","operationId":"moveFile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveFileRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /files/interdrive/move

> Move a file or folder from one drive to another in FS mode

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"MoveBetweenDrivesRequest":{"properties":{"drive_id_src":{"type":"string","format":"uuid","title":"The source drive id","description":"The id of the drive containing the file to move"},"drive_id_dst":{"type":"string","format":"uuid","title":"The destination drive id","description":"The id of the drive to move the file to"},"paths":{"items":{"$ref":"#/components/schemas/FilePathPairDTO"},"type":"array","title":"The source path","description":"The path of the file or folder to move"}},"type":"object","required":["drive_id_src","drive_id_dst","paths"],"title":"MoveBetweenDrivesRequest"},"FilePathPairDTO":{"properties":{"src":{"type":"string","title":"Src"},"dst":{"type":"string","title":"Dst"}},"type":"object","required":["src","dst"],"title":"FilePathPairDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/interdrive/move":{"post":{"tags":["files"],"summary":"Move a file or folder from one drive to another in FS mode","operationId":"moveBetweenDrives","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveBetweenDrivesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /files/interdrive/copy

> Copy a file or folder from one drive to another in FS mode

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"CopyBetweenDrivesRequest":{"properties":{"paths":{"items":{"$ref":"#/components/schemas/FilePathPairDTO"},"type":"array","title":"The source path","description":"The path of the file or folder to move"},"source_drive_id":{"type":"string","format":"uuid","title":"The source drive id","description":"The id of the drive containing the file to copy"},"destination_drive_id":{"type":"string","format":"uuid","title":"The destination drive id","description":"The id of the drive to copy the file to"}},"type":"object","required":["paths","source_drive_id","destination_drive_id"],"title":"CopyBetweenDrivesRequest"},"FilePathPairDTO":{"properties":{"src":{"type":"string","title":"Src"},"dst":{"type":"string","title":"Dst"}},"type":"object","required":["src","dst"],"title":"FilePathPairDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/interdrive/copy":{"post":{"tags":["files"],"summary":"Copy a file or folder from one drive to another in FS mode","operationId":"copyBetweenDrives","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyBetweenDrivesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Move a batch of files or folders to a new location

> NOTE: this route only works when the sources come from the same folder

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"MoveFilesRequest":{"properties":{"sources":{"items":{"type":"string","format":"path"},"type":"array","title":"The source paths","description":"The paths of the files or folders to move"},"destinations":{"items":{"type":"string","format":"path"},"type":"array","title":"The destination path","description":"The path to move the file or folder to"},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing the file to move"}},"type":"object","required":["sources","destinations","drive_id"],"title":"MoveFilesRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/move/batch":{"post":{"tags":["files"],"summary":"Move a batch of files or folders to a new location","description":"NOTE: this route only works when the sources come from the same folder","operationId":"moveFiles","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveFilesRequest"}}}},"responses":{"200":{"description":"The new paths of the files or folders","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"path"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Copy a file to a new location

> Copy a file or folder to a new location

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"CopyFileRequest":{"properties":{"source":{"type":"string","format":"path","title":"The source path","description":"Current path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},"destination":{"type":"string","format":"path","title":"The destination path","description":"New path for the file or folder, starting with the drive ID. To rename, keep the same folder and change the name."},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing the file to copy"}},"type":"object","required":["source","destination","drive_id"],"title":"CopyFileRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/copy":{"post":{"tags":["files"],"summary":"Copy a file to a new location","description":"Copy a file or folder to a new location","operationId":"copyFile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyFileRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Move a file or folder to the trash

> Move a file or folder to the trash

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"TrashFileRequest":{"properties":{"path":{"type":"string","format":"path","title":"The path to trash","description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing the file we want to move to trash"}},"type":"object","required":["path","drive_id"],"title":"TrashFileRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/trash":{"post":{"tags":["files"],"summary":"Move a file or folder to the trash","description":"Move a file or folder to the trash","operationId":"trashFile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrashFileRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Move a file or folder to the trash

> Move a file or folder to the trash

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"TrashFilesRequest":{"properties":{"paths":{"items":{"type":"string","format":"path"},"type":"array","title":"The paths to move to trash","description":"The paths of the files or folders to move to the trash"},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing the file we want to move to trash"}},"type":"object","required":["paths","drive_id"],"title":"TrashFilesRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/trash/batch":{"post":{"tags":["files"],"summary":"Move a file or folder to the trash","description":"Move a file or folder to the trash","operationId":"trashFiles","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrashFilesRequest"}}}},"responses":{"200":{"description":"The new paths of the files or folders","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"path"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete a file or folder

> Delete a file or folder

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"DeleteFileRequest":{"properties":{"path":{"type":"string","format":"path","title":"The path to delete","description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing the file we want to delete"}},"type":"object","required":["path","drive_id"],"title":"DeleteFileRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/delete":{"post":{"tags":["files"],"summary":"Delete a file or folder","description":"Delete a file or folder","operationId":"deleteFile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFileRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete files or folders in batch

> Delete files or folders in batch

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"DeleteFilesRequest":{"properties":{"paths":{"items":{"type":"string","format":"path"},"type":"array","title":"The paths to delete","description":"The paths of the files or folders to delete"},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing the file we want to delete"}},"type":"object","required":["paths","drive_id"],"title":"DeleteFilesRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/delete/batch":{"post":{"tags":["files"],"summary":"Delete files or folders in batch","description":"Delete files or folders in batch","operationId":"deleteFiles","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFilesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"path"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /files/exists

> Retrieve if a path exists or not on filesystem

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/exists":{"get":{"tags":["files"],"summary":"Retrieve if a path exists or not on filesystem","operationId":"pathExists","parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string","title":"The path to check exists for","embed":true,"format":"path"},"description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing to check if the file exists in"},"description":"The id of the drive containing to check if the file exists in"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"boolean"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /files/storage-provider

> Retrieve the storage provider for the files

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"CloudMode":{"type":"string","enum":["S3","B2","GCS","FS","LOCAL"],"title":"CloudMode"}}},"paths":{"/files/storage-provider":{"get":{"tags":["files"],"summary":"Retrieve the storage provider for the files","operationId":"getStorageProvider","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudMode"}}}},"404":{"description":"Not found"}}}}}}
```

## Get the details of assets in a path directory

> Get the total size of assets in a directory

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"DirDetailsDTO":{"properties":{"dir_size_bytes":{"type":"integer","title":"Dir Size Bytes"},"dir_num_items":{"type":"integer","title":"Dir Num Items"}},"type":"object","required":["dir_size_bytes","dir_num_items"],"title":"DirDetailsDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/details":{"get":{"tags":["files"],"summary":"Get the details of assets in a path directory","description":"Get the total size of assets in a directory","operationId":"getFolderDetails","parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string","title":"The path of the directory"},"description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this path is in"},"description":"The id of the drive this path is in"},{"name":"exclude_trash","in":"query","required":false,"schema":{"type":"boolean","title":"Exclude the trash folder","description":"Whether or not to include the trash folder in the details, if at the drive root.","default":true},"description":"Whether or not to include the trash folder in the details, if at the drive root."}],"responses":{"200":{"description":"The details of assets in the specified path directory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirDetailsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /workspaces/drives/{drive\_id}/shade-fs-token

> Get a signed JWT for a specific drive

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/workspaces/drives/{drive_id}/shade-fs-token":{"get":{"tags":["files"],"summary":"Get a signed JWT for a specific drive","operationId":"getShadeFsToken","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The Drive id"},"description":"ID of the drive. List a workspace's drives with `GET /workspaces/{workspace_id}/drives`."},{"name":"machine_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Machine ID","description":"The machine ID to embed into the JWT"},"description":"The machine ID to embed into the JWT"}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Check indexing job status for a drive

> Get the indexing job status for a drive

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"IndexingStatusDTO":{"properties":{"jobs":{"items":{"$ref":"#/components/schemas/JobsRemainingDTO"},"type":"array","title":"Jobs"}},"type":"object","required":["jobs"],"title":"IndexingStatusDTO","description":"A DTO that shows the indexing status of a drive"},"JobsRemainingDTO":{"properties":{"name":{"$ref":"#/components/schemas/IndexingJobType"},"to_do":{"type":"integer","title":"To Do"}},"type":"object","required":["name","to_do"],"title":"JobsRemainingDTO","description":"A DTO that shows the number of jobs remaining for a specific job type"},"IndexingJobType":{"type":"string","enum":["download","metadata","hashing","image_preview","video_preview","complex_preview","document_preview","cpu_proxy","gpu_proxy","edit_proxy","proxy","audio_proxy","core_audio","core_vision","color_palette","facial_recognition","custom_metadata","transcription","chunk_video","chunk_document","chunk_image","scrub_sheet"],"title":"IndexingJobType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/indexing/job-status/{drive_id}":{"get":{"tags":["files"],"summary":"Check indexing job status for a drive","description":"Get the indexing job status for a drive","operationId":"getIndexingJobStatus","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Drive Id"},"description":"ID of the drive. List a workspace's drives with `GET /workspaces/{workspace_id}/drives`."}],"responses":{"200":{"description":"The current indexing job status for the drive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexingStatusDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get the asset roots

> Get the asset roots

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"RootDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"path":{"type":"string","title":"Path"},"created":{"type":"string","format":"date-time","title":"Created"},"updated":{"type":"string","format":"date-time","title":"Updated"},"files_found":{"type":"integer","title":"Files Found","default":0},"size_bytes":{"type":"integer","title":"Size Bytes","default":0}},"type":"object","required":["id","path","created","updated"],"title":"RootDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/indexing/roots":{"get":{"tags":["files"],"summary":"Get the asset roots","description":"Get the asset roots","operationId":"listIndexingRoots","parameters":[{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive we want to add users to"},"description":"The id of the drive we want to add users to"}],"responses":{"200":{"description":"The asset roots","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RootDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Add asset roots

> Add asset roots

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"AddIndexingRootsRequest":{"properties":{"paths":{"items":{"type":"string","format":"path"},"type":"array","title":"Paths","description":"The paths to add as asset roots"},"drive_id":{"type":"string","format":"uuid","title":"Drive ID","description":"The ID of the drive"}},"type":"object","required":["paths","drive_id"],"title":"AddIndexingRootsRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/indexing/roots":{"post":{"tags":["files"],"summary":"Add asset roots","description":"Add asset roots","operationId":"addIndexingRoots","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddIndexingRootsRequest"}}}},"responses":{"200":{"description":"The ID of the new root","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"uuid"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Remove an asset root

> Remove an asset root

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"files","description":"Move, copy, rename, trash, and delete files and folders, and create folders.\n\nPaths start with the drive ID, for example\n`/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`.\nRenaming is a move to a new path in the same folder.\n\n* Prefer `POST /files/trash` over `POST /files/delete`. Trashed files can be\n  restored from the drive's trash, but deleted files can't.\n* The `/batch` variants take a list of paths in one request.\n\nTo upload files, use the\n[S3 API](https://academy.shade.inc/developers/using-shades-s3-api) or the\n[file system API](https://academy.shade.inc/developers/writing-your-own-uploader).\n`GET /workspaces/drives/{drive_id}/shade-fs-token` issues the token the file\nsystem API needs."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/indexing/roots/{root_id}":{"delete":{"tags":["files"],"summary":"Remove an asset root","description":"Remove an asset root","operationId":"removeIndexingRoot","parameters":[{"name":"root_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Root ID","description":"The ID of the root to remove"},"description":"The ID of the root to remove"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://academy.shade.inc/developers/files-and-assets/files-and-folders.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
