# Files ## POST /files/directory > Ensure a directory exists at the given path, creating if needed ```json {"openapi":"3.1.0","info":{"title":"shade","version":"dev"},"paths":{"/files/directory":{"post":{"tags":["files"],"summary":"Ensure a directory exists at the given path, creating if needed","operationId":"make_directory_files_directory_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_make_directory_files_directory_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_make_directory_files_directory_post":{"properties":{"path":{"type":"string","format":"path","title":"The path to ensure a directory for","description":"The path to ensure a directory exists at"},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive we want to make a directory in"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["path","drive_id"],"title":"Body_make_directory_files_directory_post"},"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"}}}} ``` ## 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","version":"dev"},"paths":{"/files/directory/batch":{"post":{"tags":["files"],"summary":"Ensure a list of directories exist at the given path, creating if needed","operationId":"make_directories_files_directory_batch_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_make_directories_files_directory_batch_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_make_directories_files_directory_batch_post":{"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"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["paths","drive_id"],"title":"Body_make_directories_files_directory_batch_post"},"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"}}}} ``` ## 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","version":"dev"},"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":"move_files_move_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_move_files_move_post"}}}},"responses":{"200":{"description":"The new path of the file or folder","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_move_files_move_post":{"properties":{"source":{"type":"string","format":"path","title":"The source path","description":"The path of the file or folder to move"},"destination":{"type":"string","format":"path","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"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["source","destination","drive_id"],"title":"Body_move_files_move_post"},"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"}}}} ``` ## 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","version":"dev"},"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":"move_batch_files_move_batch_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_move_batch_files_move_batch_post"}}}},"responses":{"200":{"description":"The new path of the file or folder","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"path"},"title":"Response Move Batch Files Move Batch Post"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_move_batch_files_move_batch_post":{"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"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["sources","destinations","drive_id"],"title":"Body_move_batch_files_move_batch_post"},"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"}}}} ``` ## Copy a file to a new location > Copy a file or folder to a new location ```json {"openapi":"3.1.0","info":{"title":"shade","version":"dev"},"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":"copy_files_copy_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_copy_files_copy_post"}}}},"responses":{"200":{"description":"The new path of the file","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_copy_files_copy_post":{"properties":{"source":{"type":"string","format":"path","title":"The source path","description":"The path of the file or folder to copy"},"destination":{"type":"string","format":"path","title":"The destination path","description":"The path to copy 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 copy"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["source","destination","drive_id"],"title":"Body_copy_files_copy_post"},"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"}}}} ``` ## Move a file or folder to the trash > Move a file or folder to the trash ```json {"openapi":"3.1.0","info":{"title":"shade","version":"dev"},"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":"trash_files_trash_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_trash_files_trash_post"}}}},"responses":{"200":{"description":"The new path of the file or folder","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_trash_files_trash_post":{"properties":{"path":{"type":"string","format":"path","title":"The path to trash","description":"The path of the file or folder 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"},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The share id","description":"The id of the shared root folder"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["path","drive_id"],"title":"Body_trash_files_trash_post"},"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"}}}} ``` ## Move a file or folder to the trash > Move a file or folder to the trash ```json {"openapi":"3.1.0","info":{"title":"shade","version":"dev"},"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":"trash_batch_route_files_trash_batch_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_trash_batch_route_files_trash_batch_post"}}}},"responses":{"200":{"description":"The new path of the file or folder","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"path"},"title":"Response Trash Batch Route Files Trash Batch Post"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_trash_batch_route_files_trash_batch_post":{"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"},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The share id","description":"The id of the shared root folder"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["paths","drive_id"],"title":"Body_trash_batch_route_files_trash_batch_post"},"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"}}}} ``` ## Delete a file or folder > Delete a file or folder ```json {"openapi":"3.1.0","info":{"title":"shade","version":"dev"},"paths":{"/files/delete":{"post":{"tags":["files"],"summary":"Delete a file or folder","description":"Delete a file or folder","operationId":"delete_files_delete_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_delete_files_delete_post"}}}},"responses":{"200":{"description":"The path that was deleted","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_delete_files_delete_post":{"properties":{"path":{"type":"string","format":"path","title":"The path to delete","description":"The path of the file or folder 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"},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The share id","description":"The id of the shared root folder"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["path","drive_id"],"title":"Body_delete_files_delete_post"},"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"}}}} ``` ## Delete files or folders in batch > Delete files or folders in batch ```json {"openapi":"3.1.0","info":{"title":"shade","version":"dev"},"paths":{"/files/delete/batch":{"post":{"tags":["files"],"summary":"Delete files or folders in batch","description":"Delete files or folders in batch","operationId":"delete_batch_route_files_delete_batch_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_delete_batch_route_files_delete_batch_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"path"},"title":"Response Delete Batch Route Files Delete Batch Post"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_delete_batch_route_files_delete_batch_post":{"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"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["paths","drive_id"],"title":"Body_delete_batch_route_files_delete_batch_post"},"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"}}}} ``` ## GET /files/exists > Retrieve if a path exists or not on filesystem ```json {"openapi":"3.1.0","info":{"title":"shade","version":"dev"},"paths":{"/files/exists":{"get":{"tags":["files"],"summary":"Retrieve if a path exists or not on filesystem","operationId":"exists_files_exists_get","parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string","title":"The path to check exists for","description":"The path to determine if it exists in the filesystem or not","embed":true,"format":"path"},"description":"The path to determine if it exists in the filesystem or not"},{"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"},{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_exists_files_exists_get"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"boolean","title":"Response Exists Files Exists Get"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_exists_files_exists_get":{"properties":{"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","title":"Body_exists_files_exists_get"},"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"}}}} ``` ## GET /files/storage-provider > Retrieve the storage provider for the files ```json {"openapi":"3.1.0","info":{"title":"shade","version":"dev"},"paths":{"/files/storage-provider":{"get":{"tags":["files"],"summary":"Retrieve the storage provider for the files","operationId":"get_storage_provider_files_storage_provider_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudMode"}}}},"404":{"description":"Not found"}}}}},"components":{"schemas":{"CloudMode":{"type":"string","enum":["S3","B2","GCS","FS","LOCAL"],"title":"CloudMode"}}}} ``` ## 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","version":"dev"},"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":"get_dir_details_files_details_get","parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string","title":"The path of the directory","description":"The path to retrieve the total size for"},"description":"The path to retrieve the total size for"},{"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."},{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_get_dir_details_files_details_get"}}}},"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"}}}}}}}},"components":{"schemas":{"Body_get_dir_details_files_details_get":{"properties":{"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","title":"Body_get_dir_details_files_details_get"},"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"}}}} ``` --- # Agent Instructions: 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: ``` GET https://academy.shade.inc/developers/files.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.