> 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/workspaces-and-drives/drives.md).

# Drives

A drive is a top-level storage space inside a workspace, with its own files, metadata fields, collections, and permissions. Almost every other route takes a `drive_id`.

* List a workspace's drives, with your role and allowed actions on each, with `GET /workspaces/{workspace_id}/drives`.
* Get one drive with `GET /workspaces/drives/{drive_id}`.

## GET /public/drive-templates

> Get all public drive templates

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[],"paths":{"/public/drive-templates":{"get":{"tags":["drives"],"summary":"Get all public drive templates","operationId":"listDriveTemplates","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/DriveTemplateDTO"},"type":"array"}}}},"404":{"description":"Not found"}}}}},"components":{"schemas":{"DriveTemplateDTO":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"dynamic_views":{"items":{"$ref":"#/components/schemas/DynamicView"},"type":"array","title":"Dynamic Views"},"metadata_attributes":{"items":{"$ref":"#/components/schemas/MetadataAttribute-Output"},"type":"array","title":"Metadata Attributes"}},"type":"object","required":["id","name","description","dynamic_views","metadata_attributes"],"title":"DriveTemplateDTO"},"DynamicView":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/AddedFilterForStorage"},"type":"array"},{"type":"null"}],"title":"Filters"},"columns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Columns"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"is_locked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Locked"},"is_private":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Private"},"display_settings":{"anyOf":[{"$ref":"#/components/schemas/DynamicViewDisplaySettings"},{"type":"null"}]},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"},"icon_type":{"anyOf":[{"$ref":"#/components/schemas/DynamicViewIconType"},{"type":"null"}]},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort"}},"type":"object","required":["id","name"],"title":"DynamicView"},"AddedFilterForStorage":{"properties":{"id":{"title":"Id"},"options":{"items":{"$ref":"#/components/schemas/FilterOption"},"type":"array","title":"Options"},"clause":{"$ref":"#/components/schemas/FilterClauseVal"},"ignore_options":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ignore Options"}},"type":"object","required":["id","options","clause"],"title":"AddedFilterForStorage"},"FilterOption":{"properties":{"client_val":{"type":"string","title":"Client Val"},"server_val":{"type":"string","title":"Server Val"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"}},"type":"object","required":["client_val","server_val"],"title":"FilterOption"},"FilterClauseVal":{"type":"string","enum":["is","is any of","is not","is true","is false","is not true","is not false","has","doesn't have","before","after","between","is directly in","is under","is not in","<","< any of","<=","<= any of",">","> any of",">=",">= any of","hasn't started","in progress of","completed","failed","includes","does not include","contains","does not contain","does not start with","starts with","end with","is empty","is not empty"],"title":"FilterClauseVal","description":"Filter Clause Values Enum. Contains all filter clause values"},"DynamicViewDisplaySettings":{"properties":{"card_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Card Size"},"thumbnail_view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail View"},"thumbnail_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Size"},"view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"},"metadata_attribute_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata Attribute Ids"},"flatten_directories":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Flatten Directories"},"tile_rounded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tile Rounded"}},"type":"object","title":"DynamicViewDisplaySettings"},"DynamicViewIconType":{"type":"string","enum":["color","emoji","url"],"title":"DynamicViewIconType"},"MetadataAttribute-Output":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"keys":{"items":{"type":"string"},"type":"array","title":"Keys"},"value_type":{"$ref":"#/components/schemas/MetadataAttributeType"},"description":{"type":"string","title":"Description"},"location":{"$ref":"#/components/schemas/MetadataAttributeLocation"},"default":{"anyOf":[{},{"type":"null"}],"title":"Default"},"group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group"},"options":{"anyOf":[{"items":{"$ref":"#/components/schemas/MetadataAttributeSelectOption"},"type":"array"},{"type":"null"}],"title":"Options"},"add_new_options":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Add New Options","default":true},"restrict_to_types":{"anyOf":[{"items":{"$ref":"#/components/schemas/AssetType"},"type":"array"},{"type":"null"}],"title":"Restrict To Types"},"automated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Automated","default":false},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Archived","default":false},"locked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Locked","default":false},"deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Deleted","default":false},"relation_config":{"anyOf":[{"$ref":"#/components/schemas/RelationConfig-Output"},{"type":"null"}]},"lookup_config":{"anyOf":[{"$ref":"#/components/schemas/LookupConfig"},{"type":"null"}]}},"type":"object","required":["id","name","keys","value_type","description","location"],"title":"MetadataAttribute"},"MetadataAttributeType":{"type":"string","enum":["str","single_select","multi_select","float","int","bool","datetime","rating","relation","lookup"],"title":"MetadataAttributeType","description":"The type of value a metadata attribute holds."},"MetadataAttributeLocation":{"type":"string","enum":["system","custom","asset"],"title":"MetadataAttributeLocation"},"MetadataAttributeSelectOption":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"color":{"$ref":"#/components/schemas/MetadataAttributeSelectOptionColor"},"user":{"type":"boolean","title":"User"},"archived":{"type":"boolean","title":"Archived","default":false}},"type":"object","required":["id","name","color","user"],"title":"MetadataAttributeSelectOption"},"MetadataAttributeSelectOptionColor":{"type":"string","enum":["pink","red","yellow","light_green","dark_green","light_blue","dark_blue","purple"],"title":"MetadataAttributeSelectOptionColor"},"AssetType":{"type":"string","enum":["IMAGE","VIDEO","AUDIO","DOCUMENT","HDR","HDRI","PHOTOSHOP","ILLUSTRATOR","EXR","OBJECT","VECTOR","OTHER","MAYA","MAX","BLENDER","HOUDINI","UNREAL","UNITY","AFTER_EFFECTS","MOGRT"],"title":"AssetType"},"RelationConfig-Output":{"properties":{"target":{"oneOf":[{"$ref":"#/components/schemas/AssetTarget"},{"$ref":"#/components/schemas/CustomObjectTarget"},{"$ref":"#/components/schemas/IndividualTarget"},{"$ref":"#/components/schemas/UserTarget"}],"title":"Target","discriminator":{"propertyName":"kind","mapping":{"asset":"#/components/schemas/AssetTarget","custom_object":"#/components/schemas/CustomObjectTarget","individual":"#/components/schemas/IndividualTarget","user":"#/components/schemas/UserTarget"}}},"paired_to":{"anyOf":[{"$ref":"#/components/schemas/PairedTo"},{"type":"null"}]},"inverse":{"anyOf":[{"$ref":"#/components/schemas/InverseConfig"},{"type":"null"}]}},"type":"object","required":["target"],"title":"RelationConfig"},"AssetTarget":{"properties":{"kind":{"type":"string","const":"asset","title":"Kind","default":"asset"}},"type":"object","title":"AssetTarget"},"CustomObjectTarget":{"properties":{"kind":{"type":"string","const":"custom_object","title":"Kind","default":"custom_object"},"database_id":{"type":"string","format":"uuid","title":"Database Id"}},"type":"object","required":["database_id"],"title":"CustomObjectTarget"},"IndividualTarget":{"properties":{"kind":{"type":"string","const":"individual","title":"Kind","default":"individual"}},"type":"object","title":"IndividualTarget"},"UserTarget":{"properties":{"kind":{"type":"string","const":"user","title":"Kind","default":"user"}},"type":"object","title":"UserTarget"},"PairedTo":{"properties":{"target":{"oneOf":[{"$ref":"#/components/schemas/AssetTarget"},{"$ref":"#/components/schemas/CustomObjectTarget"},{"$ref":"#/components/schemas/IndividualTarget"},{"$ref":"#/components/schemas/UserTarget"}],"title":"Target","discriminator":{"propertyName":"kind","mapping":{"asset":"#/components/schemas/AssetTarget","custom_object":"#/components/schemas/CustomObjectTarget","individual":"#/components/schemas/IndividualTarget","user":"#/components/schemas/UserTarget"}}},"column_id":{"type":"string","format":"uuid","title":"Column Id"},"type_name":{"type":"string","title":"Type Name"},"column_name":{"type":"string","title":"Column Name"}},"type":"object","required":["target","column_id","type_name","column_name"],"title":"PairedTo","description":"``target`` describes the kind that OWNS the forward column; the union\nkeeps room for non-custom-object owners (e.g. future user-source forward\ncolumns)."},"InverseConfig":{"properties":{"enabled":{"type":"boolean","title":"Enabled","default":false},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"type":"object","title":"InverseConfig"},"LookupConfig":{"properties":{"path":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":3,"minItems":1,"title":"Path"},"path_inverse_flags":{"items":{"type":"boolean"},"type":"array","title":"Path Inverse Flags"},"target_column_id":{"type":"string","format":"uuid","title":"Target Column Id"},"target_value_type":{"type":"string","title":"Target Value Type","default":""},"aggregation":{"$ref":"#/components/schemas/LookupAggregation","default":"all"}},"type":"object","required":["path","target_column_id"],"title":"LookupConfig","description":"``path`` is the ordered list of hop ids the user clicked. Each entry\nmay be a real forward ``DatabaseColumnModel.id`` or an\n``inverse_database_columns.id`` synthetic id — the server canonicalizes\nto forward column ids at write time and persists a parallel\n``path_inverse_flags`` derived from which form each entry was. Clients\ndo not need to set ``path_inverse_flags`` on writes; any value supplied\nis ignored and overwritten by the resolver. On reads it reflects the\nstored direction array, parallel to ``path``.\n\n``target_column_id`` is the scalar attribute on the final related object.\n``target_value_type`` is ignored on the request side (the server reads it\nfrom the target column) — the default empty string just lets the request\nDTO round-trip with a placeholder. ``aggregation`` defaults to ALL when\nomitted to keep wire-compat with frontends that don't set it explicitly."},"LookupAggregation":{"type":"string","enum":["first","all","count","sum","avg","min","max"],"title":"LookupAggregation"}}}}
```

## Gets a drive from the drive\_id

> Gets a drive from the drive\_id

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"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":{"DriveWithActionsDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"icon":{"type":"string","title":"Icon"},"settings":{"$ref":"#/components/schemas/DriveSettings"},"type":{"$ref":"#/components/schemas/DriveType"},"identifier":{"type":"string","title":"Identifier"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"member_inherited_role":{"$ref":"#/components/schemas/DriveRole"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"byos":{"anyOf":[{"$ref":"#/components/schemas/DriveByosData"},{"type":"null"}]},"default_storage_backend":{"anyOf":[{"$ref":"#/components/schemas/DriveDefaultStorageBackend"},{"type":"null"}]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions"},"role":{"$ref":"#/components/schemas/DriveRole"},"is_workspace_member":{"type":"boolean","title":"Is Workspace Member","default":false}},"type":"object","required":["id","name","description","icon","settings","type","identifier","icon_type","member_inherited_role","invite_id","workspace_id","byos","default_storage_backend","actions","role"],"title":"DriveWithActionsDTO"},"DriveSettings":{"properties":{"max_storage_bytes":{"type":"integer","title":"Max Storage Bytes"},"mount_path_macos":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Macos"},"mount_path_linux":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Linux"},"mount_path_windows":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Windows"}},"type":"object","required":["max_storage_bytes"],"title":"DriveSettings"},"DriveType":{"type":"string","enum":["catalog","magic","vault"],"title":"DriveType"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"DriveRole":{"type":"integer","enum":[50,40,30,20,17,15,10,0],"title":"DriveRole","description":"A user's role on a drive, folder, or file. Higher values grant more access."},"DriveByosData":{"properties":{"bucket":{"type":"string","title":"Bucket"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["bucket","endpoint"],"title":"DriveByosData"},"DriveDefaultStorageBackend":{"properties":{"provider":{"type":"string","title":"Provider"},"bucket":{"type":"string","title":"Bucket"}},"type":"object","required":["provider","bucket"],"title":"DriveDefaultStorageBackend"},"Action":{"type":"string","enum":["manage","edit","share","comment","edit_metadata","download","read","read_asset_details","read_metadata","manage_webhooks","manage_drive","view_stack_versions"],"title":"Action","description":"An action a user or share link is allowed to take."},"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}":{"get":{"tags":["drives"],"summary":"Gets a drive from the drive_id","description":"Gets a drive from the drive_id","operationId":"getWorkspaceDrive","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`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriveWithActionsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## PUT /workspaces/drives/{drive\_id}

> Updates drive

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"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":{"UpdateDriveRequest":{"properties":{"name":{"type":"string","title":"Drive Name"},"description":{"type":"string","title":"Description"},"icon":{"type":"string","title":"Drive Icon"},"icon_type":{"$ref":"#/components/schemas/DriveIconType","title":"Drive Icon"},"member_inherited_role":{"$ref":"#/components/schemas/DriveRole","title":"Member Inherited Role"}},"type":"object","required":["name","description","icon","icon_type","member_inherited_role"],"title":"UpdateDriveRequest"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"DriveRole":{"type":"integer","enum":[50,40,30,20,17,15,10,0],"title":"DriveRole","description":"A user's role on a drive, folder, or file. Higher values grant more access."},"DriveWithActionsDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"icon":{"type":"string","title":"Icon"},"settings":{"$ref":"#/components/schemas/DriveSettings"},"type":{"$ref":"#/components/schemas/DriveType"},"identifier":{"type":"string","title":"Identifier"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"member_inherited_role":{"$ref":"#/components/schemas/DriveRole"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"byos":{"anyOf":[{"$ref":"#/components/schemas/DriveByosData"},{"type":"null"}]},"default_storage_backend":{"anyOf":[{"$ref":"#/components/schemas/DriveDefaultStorageBackend"},{"type":"null"}]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions"},"role":{"$ref":"#/components/schemas/DriveRole"},"is_workspace_member":{"type":"boolean","title":"Is Workspace Member","default":false}},"type":"object","required":["id","name","description","icon","settings","type","identifier","icon_type","member_inherited_role","invite_id","workspace_id","byos","default_storage_backend","actions","role"],"title":"DriveWithActionsDTO"},"DriveSettings":{"properties":{"max_storage_bytes":{"type":"integer","title":"Max Storage Bytes"},"mount_path_macos":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Macos"},"mount_path_linux":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Linux"},"mount_path_windows":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Windows"}},"type":"object","required":["max_storage_bytes"],"title":"DriveSettings"},"DriveType":{"type":"string","enum":["catalog","magic","vault"],"title":"DriveType"},"DriveByosData":{"properties":{"bucket":{"type":"string","title":"Bucket"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["bucket","endpoint"],"title":"DriveByosData"},"DriveDefaultStorageBackend":{"properties":{"provider":{"type":"string","title":"Provider"},"bucket":{"type":"string","title":"Bucket"}},"type":"object","required":["provider","bucket"],"title":"DriveDefaultStorageBackend"},"Action":{"type":"string","enum":["manage","edit","share","comment","edit_metadata","download","read","read_asset_details","read_metadata","manage_webhooks","manage_drive","view_stack_versions"],"title":"Action","description":"An action a user or share link is allowed to take."},"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}":{"put":{"tags":["drives"],"summary":"Updates drive","operationId":"updateDrive","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`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDriveRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriveWithActionsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## DELETE /workspaces/drives/{drive\_id}

> Delete a drive by drive\_id

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"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}":{"delete":{"tags":["drives"],"summary":"Delete a drive by drive_id","operationId":"deleteDrive","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The workspace id"},"description":"ID of the drive. List a workspace's drives with `GET /workspaces/{workspace_id}/drives`."}],"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"}}}}}}}}}
```

## PUT /workspaces/drives/{drive\_id}/settings

> Update drive settings

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"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":{"DriveSettingsPatch":{"properties":{"max_storage_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Storage Bytes"},"mount_path_macos":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Macos"},"mount_path_linux":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Linux"},"mount_path_windows":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Windows"}},"type":"object","title":"DriveSettingsPatch"},"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}/settings":{"put":{"tags":["drives"],"summary":"Update drive settings","operationId":"updateDriveSettings","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`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriveSettingsPatch"}}}},"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"}}}}}}}}}
```

## GET /workspaces/{workspace\_id}/drives

> Lists all the drives for a specific workspace

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"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":{"DriveWithActionsDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"icon":{"type":"string","title":"Icon"},"settings":{"$ref":"#/components/schemas/DriveSettings"},"type":{"$ref":"#/components/schemas/DriveType"},"identifier":{"type":"string","title":"Identifier"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"member_inherited_role":{"$ref":"#/components/schemas/DriveRole"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"byos":{"anyOf":[{"$ref":"#/components/schemas/DriveByosData"},{"type":"null"}]},"default_storage_backend":{"anyOf":[{"$ref":"#/components/schemas/DriveDefaultStorageBackend"},{"type":"null"}]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions"},"role":{"$ref":"#/components/schemas/DriveRole"},"is_workspace_member":{"type":"boolean","title":"Is Workspace Member","default":false}},"type":"object","required":["id","name","description","icon","settings","type","identifier","icon_type","member_inherited_role","invite_id","workspace_id","byos","default_storage_backend","actions","role"],"title":"DriveWithActionsDTO"},"DriveSettings":{"properties":{"max_storage_bytes":{"type":"integer","title":"Max Storage Bytes"},"mount_path_macos":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Macos"},"mount_path_linux":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Linux"},"mount_path_windows":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Windows"}},"type":"object","required":["max_storage_bytes"],"title":"DriveSettings"},"DriveType":{"type":"string","enum":["catalog","magic","vault"],"title":"DriveType"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"DriveRole":{"type":"integer","enum":[50,40,30,20,17,15,10,0],"title":"DriveRole","description":"A user's role on a drive, folder, or file. Higher values grant more access."},"DriveByosData":{"properties":{"bucket":{"type":"string","title":"Bucket"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["bucket","endpoint"],"title":"DriveByosData"},"DriveDefaultStorageBackend":{"properties":{"provider":{"type":"string","title":"Provider"},"bucket":{"type":"string","title":"Bucket"}},"type":"object","required":["provider","bucket"],"title":"DriveDefaultStorageBackend"},"Action":{"type":"string","enum":["manage","edit","share","comment","edit_metadata","download","read","read_asset_details","read_metadata","manage_webhooks","manage_drive","view_stack_versions"],"title":"Action","description":"An action a user or share link is allowed to take."},"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/{workspace_id}/drives":{"get":{"tags":["drives"],"summary":"Lists all the drives for a specific workspace","operationId":"listWorkspaceDrives","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The workspace id"},"description":"ID of the workspace. List yours with `GET /workspaces`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DriveWithActionsDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Creates a drive in a workspace

> Create a Drive

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"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":{"CreateWorkspaceDriveRequest":{"properties":{"name":{"type":"string","title":"Drive Name"},"description":{"type":"string","title":"Drive Description"},"type":{"$ref":"#/components/schemas/DriveType","title":"Drive Type"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Drive Icon"},"icon_type":{"anyOf":[{"$ref":"#/components/schemas/DriveIconType"},{"type":"null"}],"title":"Drive Icon Type"},"byos":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"BYOS Info"},"default_storage_backend":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Default Provider info"},"template_drive_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Template Drive"},"public_template_key":{"anyOf":[{"$ref":"#/components/schemas/PublicDriveTemplate"},{"type":"null"}],"title":"Public Template Key"}},"type":"object","required":["name","description","type","icon_type"],"title":"CreateWorkspaceDriveRequest"},"DriveType":{"type":"string","enum":["catalog","magic","vault"],"title":"DriveType"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"PublicDriveTemplate":{"type":"string","enum":["video_production","commercial_photography","marketing_agency"],"title":"PublicDriveTemplate"},"DriveWithActionsDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"icon":{"type":"string","title":"Icon"},"settings":{"$ref":"#/components/schemas/DriveSettings"},"type":{"$ref":"#/components/schemas/DriveType"},"identifier":{"type":"string","title":"Identifier"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"member_inherited_role":{"$ref":"#/components/schemas/DriveRole"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"byos":{"anyOf":[{"$ref":"#/components/schemas/DriveByosData"},{"type":"null"}]},"default_storage_backend":{"anyOf":[{"$ref":"#/components/schemas/DriveDefaultStorageBackend"},{"type":"null"}]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions"},"role":{"$ref":"#/components/schemas/DriveRole"},"is_workspace_member":{"type":"boolean","title":"Is Workspace Member","default":false}},"type":"object","required":["id","name","description","icon","settings","type","identifier","icon_type","member_inherited_role","invite_id","workspace_id","byos","default_storage_backend","actions","role"],"title":"DriveWithActionsDTO"},"DriveSettings":{"properties":{"max_storage_bytes":{"type":"integer","title":"Max Storage Bytes"},"mount_path_macos":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Macos"},"mount_path_linux":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Linux"},"mount_path_windows":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Windows"}},"type":"object","required":["max_storage_bytes"],"title":"DriveSettings"},"DriveRole":{"type":"integer","enum":[50,40,30,20,17,15,10,0],"title":"DriveRole","description":"A user's role on a drive, folder, or file. Higher values grant more access."},"DriveByosData":{"properties":{"bucket":{"type":"string","title":"Bucket"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["bucket","endpoint"],"title":"DriveByosData"},"DriveDefaultStorageBackend":{"properties":{"provider":{"type":"string","title":"Provider"},"bucket":{"type":"string","title":"Bucket"}},"type":"object","required":["provider","bucket"],"title":"DriveDefaultStorageBackend"},"Action":{"type":"string","enum":["manage","edit","share","comment","edit_metadata","download","read","read_asset_details","read_metadata","manage_webhooks","manage_drive","view_stack_versions"],"title":"Action","description":"An action a user or share link is allowed to take."},"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/{workspace_id}/drives":{"post":{"tags":["drives"],"summary":"Creates a drive in a workspace","description":"Create a Drive","operationId":"createWorkspaceDrive","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The workspace id"},"description":"ID of the workspace. List yours with `GET /workspaces`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceDriveRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriveWithActionsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Lists all user drives (including demo workspace drives)

> This route is used to get all the drives for a user.\
> The frontend uses this to determine which shadefs drives should be kept/removed

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"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/drive-ids":{"get":{"tags":["drives"],"summary":"Lists all user drives (including demo workspace drives)","description":"This route is used to get all the drives for a user.\nThe frontend uses this to determine which shadefs drives should be kept/removed","operationId":"listAllUserDrives","responses":{"200":{"description":"Successful Response","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"}}}}}}}}}
```

## Lists all the drives and your permission level for them

> This is used for the /admin routes

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"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":{"DrivePermissionsDTO":{"properties":{"drives_you_can_manage":{"items":{"$ref":"#/components/schemas/DriveDTO"},"type":"array","title":"Drives You Can Manage"},"drives_you_can_read":{"items":{"$ref":"#/components/schemas/DriveDTO"},"type":"array","title":"Drives You Can Read"}},"type":"object","required":["drives_you_can_manage","drives_you_can_read"],"title":"DrivePermissionsDTO"},"DriveDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"icon":{"type":"string","title":"Icon"},"settings":{"$ref":"#/components/schemas/DriveSettings"},"type":{"$ref":"#/components/schemas/DriveType"},"identifier":{"type":"string","title":"Identifier"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"member_inherited_role":{"$ref":"#/components/schemas/DriveRole"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"byos":{"anyOf":[{"$ref":"#/components/schemas/DriveByosData"},{"type":"null"}]},"default_storage_backend":{"anyOf":[{"$ref":"#/components/schemas/DriveDefaultStorageBackend"},{"type":"null"}]}},"type":"object","required":["id","name","description","icon","settings","type","identifier","icon_type","member_inherited_role","invite_id","workspace_id","byos","default_storage_backend"],"title":"DriveDTO"},"DriveSettings":{"properties":{"max_storage_bytes":{"type":"integer","title":"Max Storage Bytes"},"mount_path_macos":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Macos"},"mount_path_linux":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Linux"},"mount_path_windows":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mount Path Windows"}},"type":"object","required":["max_storage_bytes"],"title":"DriveSettings"},"DriveType":{"type":"string","enum":["catalog","magic","vault"],"title":"DriveType"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"DriveRole":{"type":"integer","enum":[50,40,30,20,17,15,10,0],"title":"DriveRole","description":"A user's role on a drive, folder, or file. Higher values grant more access."},"DriveByosData":{"properties":{"bucket":{"type":"string","title":"Bucket"},"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["bucket","endpoint"],"title":"DriveByosData"},"DriveDefaultStorageBackend":{"properties":{"provider":{"type":"string","title":"Provider"},"bucket":{"type":"string","title":"Bucket"}},"type":"object","required":["provider","bucket"],"title":"DriveDefaultStorageBackend"},"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/{workspace_id}/drives/permissions":{"get":{"tags":["drives"],"summary":"Lists all the drives and your permission level for them","description":"This is used for the /admin routes","operationId":"listWorkspaceDrivesWithPermissions","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The workspace id"},"description":"ID of the workspace. List yours with `GET /workspaces`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrivePermissionsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /workspaces/{workspace\_domain}/drives/{drive\_identifier}/identifier

> Gets a drive\_id from an identifier

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"drives","description":"A drive is a top-level storage space inside a workspace, with its own files,\nmetadata fields, collections, and permissions. Almost every other route takes\na `drive_id`.\n\n* List a workspace's drives, with your role and allowed actions on each, with\n  `GET /workspaces/{workspace_id}/drives`.\n* Get one drive with `GET /workspaces/drives/{drive_id}`."}],"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/{workspace_domain}/drives/{drive_identifier}/identifier":{"get":{"tags":["drives"],"summary":"Gets a drive_id from an identifier","operationId":"getDriveIdFromIdentifier","parameters":[{"name":"drive_identifier","in":"path","required":true,"schema":{"type":"string","title":"The drive identifier"}},{"name":"workspace_domain","in":"path","required":true,"schema":{"type":"string","title":"The workspace id or domain"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"string","format":"uuid"}}}},"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/workspaces-and-drives/drives.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.
