> 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/organize/collections.md).

# Collections

A collection is a hand-picked set of assets, like a playlist, that can span folders. Collections can be shared publicly with their own link settings.

See [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.

* Create one with `POST /collections`, then add assets with `POST /collections/{collection_id}/assets`.
* To list a collection's assets, call `POST /search` with `collection_id`.
* `POST /collections/{collection_id}/directories` adds whole folders.

## List all collections in a specific drive

> Get a listing of all the collections in the database

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"CollectionDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserDTOBase"},{"type":"null"}]},"is_public_enabled":{"type":"boolean","title":"Is Public Enabled"},"allowed_actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Allowed Actions"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"settings":{"$ref":"#/components/schemas/CollectionSettings-Output"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"icon":{"type":"string","title":"Icon"},"icon_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"background_image":{"type":"string","title":"Background Image"},"background_image_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]},"is_expired":{"type":"boolean","title":"Is Expired","default":false},"password_protected":{"type":"boolean","title":"Password Protected"},"expiration_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expiration Date"}},"type":"object","required":["id","name","description","drive_id","created_by","is_public_enabled","allowed_actions","invite_id","settings","icon_type","icon","background_image","password_protected"],"title":"CollectionDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"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."},"CollectionSettings-Output":{"properties":{"view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"},"thumbnail_view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail View"},"thumbnail_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Size"},"card_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Card Size"},"metadata_attribute_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata Attribute Ids"},"tile_rounded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tile Rounded"},"watermarking_config":{"anyOf":[{"$ref":"#/components/schemas/WatermarkingConfiguration"},{"type":"null"}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSort"},{"type":"null"}]},"watermark_proxies":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Watermark Proxies","readOnly":true}},"type":"object","required":["watermark_proxies"],"title":"CollectionSettings"},"WatermarkingConfiguration":{"properties":{"mode":{"$ref":"#/components/schemas/WatermarkingMode"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"position":{"anyOf":[{"$ref":"#/components/schemas/WatermarkPosition"},{"type":"null"}]},"font_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Font Size"}},"type":"object","required":["mode"],"title":"WatermarkingConfiguration","description":"Typed configuration for text-based watermarking and transcoder options."},"WatermarkingMode":{"type":"string","enum":["session","text"],"title":"WatermarkingMode"},"WatermarkPosition":{"type":"string","enum":["top_left","top_center","top_right","center","bottom_left","bottom_center","bottom_right"],"title":"WatermarkPosition"},"CollectionSettingSort":{"properties":{"attribute":{"type":"string","title":"Attribute"},"direction":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSortDirection"},{"type":"null"}]}},"type":"object","required":["attribute"],"title":"CollectionSettingSort"},"CollectionSettingSortDirection":{"type":"string","enum":["ASC","DESC","CUSTOM"],"title":"CollectionSettingSortDirection"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"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":{"/collections":{"get":{"tags":["collections"],"summary":"List all collections in a specific drive","description":"Get a listing of all the collections in the database","operationId":"listCollections","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 get collections from"},"description":"The id of the drive we want to get collections from"}],"responses":{"200":{"description":"A list of all collections in the specified drive.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CollectionDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create a collection

> Create a new user collection of assets

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"CreateCollectionRequest":{"properties":{"name":{"type":"string","title":"The name of the user collection","description":"The name of the user collection to be created"},"description":{"type":"string","title":"The description of the user collection","description":"The description of the user collection to be created","default":""},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to create the collection in"}},"type":"object","required":["name","drive_id"],"title":"CreateCollectionRequest"},"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":{"/collections":{"post":{"tags":["collections"],"summary":"Create a collection","description":"Create a new user collection of assets","operationId":"createCollection","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectionRequest"}}}},"responses":{"200":{"description":"The id of the created user collection","content":{"application/json":{"schema":{"type":"string","format":"uuid"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get a collection by its id

> Get a collection by id

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"FullCollectionDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserDTOBase"},{"type":"null"}]},"is_public_enabled":{"type":"boolean","title":"Is Public Enabled"},"allowed_actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Allowed Actions"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"settings":{"$ref":"#/components/schemas/CollectionSettings-Output"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"icon":{"type":"string","title":"Icon"},"icon_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"background_image":{"type":"string","title":"Background Image"},"background_image_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]},"is_expired":{"type":"boolean","title":"Is Expired","default":false},"password_protected":{"type":"boolean","title":"Password Protected"},"expiration_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expiration Date"},"num_assets":{"type":"integer","title":"Num Assets"},"num_directories":{"type":"integer","title":"Num Directories"},"size":{"type":"number","title":"Size"}},"type":"object","required":["id","name","description","drive_id","created_by","is_public_enabled","allowed_actions","invite_id","settings","icon_type","icon","background_image","password_protected","num_assets","num_directories","size"],"title":"FullCollectionDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"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."},"CollectionSettings-Output":{"properties":{"view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"},"thumbnail_view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail View"},"thumbnail_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Size"},"card_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Card Size"},"metadata_attribute_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata Attribute Ids"},"tile_rounded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tile Rounded"},"watermarking_config":{"anyOf":[{"$ref":"#/components/schemas/WatermarkingConfiguration"},{"type":"null"}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSort"},{"type":"null"}]},"watermark_proxies":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Watermark Proxies","readOnly":true}},"type":"object","required":["watermark_proxies"],"title":"CollectionSettings"},"WatermarkingConfiguration":{"properties":{"mode":{"$ref":"#/components/schemas/WatermarkingMode"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"position":{"anyOf":[{"$ref":"#/components/schemas/WatermarkPosition"},{"type":"null"}]},"font_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Font Size"}},"type":"object","required":["mode"],"title":"WatermarkingConfiguration","description":"Typed configuration for text-based watermarking and transcoder options."},"WatermarkingMode":{"type":"string","enum":["session","text"],"title":"WatermarkingMode"},"WatermarkPosition":{"type":"string","enum":["top_left","top_center","top_right","center","bottom_left","bottom_center","bottom_right"],"title":"WatermarkPosition"},"CollectionSettingSort":{"properties":{"attribute":{"type":"string","title":"Attribute"},"direction":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSortDirection"},{"type":"null"}]}},"type":"object","required":["attribute"],"title":"CollectionSettingSort"},"CollectionSettingSortDirection":{"type":"string","enum":["ASC","DESC","CUSTOM"],"title":"CollectionSettingSortDirection"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"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":{"/collections/{collection_id}":{"get":{"tags":["collections"],"summary":"Get a collection by its id","description":"Get a collection by id","operationId":"getCollection","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id"},"description":"ID of the collection. List a drive's collections with `GET /collections`."}],"responses":{"200":{"description":"The collection","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/FullCollectionDTO"},{"type":"null"}]}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update a collection

> Update a collection

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"UpdateCollectionRequest":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection name","description":"The new name for the collection"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection description","description":"The new description for the collection"},"is_public_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is public visible"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"},"icon_type":{"anyOf":[{"$ref":"#/components/schemas/DriveIconType"},{"type":"null"}],"title":"Icon type"},"allowed_actions":{"anyOf":[{"items":{"$ref":"#/components/schemas/Action"},"type":"array"},{"type":"null"}],"title":"Allowed Actions"},"background_image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"background_image"},"settings":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettings-Input"},{"type":"null"}],"title":"Settings"},"expiration_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"The expiration date of the collection","description":"The expiration date of the collection"},"password":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password of the collection","description":"The password of the collection"},"removed_password":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Removed password","description":"remove the collection password","default":false},"removed_expiration_date":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Removed expiration date","description":"Remove the collection expiration date","default":false}},"type":"object","title":"UpdateCollectionRequest"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"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."},"CollectionSettings-Input":{"properties":{"view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"},"thumbnail_view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail View"},"thumbnail_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Size"},"card_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Card Size"},"metadata_attribute_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata Attribute Ids"},"tile_rounded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tile Rounded"},"watermarking_config":{"anyOf":[{"$ref":"#/components/schemas/WatermarkingConfiguration"},{"type":"null"}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSort"},{"type":"null"}]}},"type":"object","title":"CollectionSettings"},"WatermarkingConfiguration":{"properties":{"mode":{"$ref":"#/components/schemas/WatermarkingMode"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"position":{"anyOf":[{"$ref":"#/components/schemas/WatermarkPosition"},{"type":"null"}]},"font_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Font Size"}},"type":"object","required":["mode"],"title":"WatermarkingConfiguration","description":"Typed configuration for text-based watermarking and transcoder options."},"WatermarkingMode":{"type":"string","enum":["session","text"],"title":"WatermarkingMode"},"WatermarkPosition":{"type":"string","enum":["top_left","top_center","top_right","center","bottom_left","bottom_center","bottom_right"],"title":"WatermarkPosition"},"CollectionSettingSort":{"properties":{"attribute":{"type":"string","title":"Attribute"},"direction":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSortDirection"},{"type":"null"}]}},"type":"object","required":["attribute"],"title":"CollectionSettingSort"},"CollectionSettingSortDirection":{"type":"string","enum":["ASC","DESC","CUSTOM"],"title":"CollectionSettingSortDirection"},"CollectionDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserDTOBase"},{"type":"null"}]},"is_public_enabled":{"type":"boolean","title":"Is Public Enabled"},"allowed_actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Allowed Actions"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"settings":{"$ref":"#/components/schemas/CollectionSettings-Output"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"icon":{"type":"string","title":"Icon"},"icon_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"background_image":{"type":"string","title":"Background Image"},"background_image_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]},"is_expired":{"type":"boolean","title":"Is Expired","default":false},"password_protected":{"type":"boolean","title":"Password Protected"},"expiration_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expiration Date"}},"type":"object","required":["id","name","description","drive_id","created_by","is_public_enabled","allowed_actions","invite_id","settings","icon_type","icon","background_image","password_protected"],"title":"CollectionDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"CollectionSettings-Output":{"properties":{"view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"},"thumbnail_view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail View"},"thumbnail_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Size"},"card_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Card Size"},"metadata_attribute_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata Attribute Ids"},"tile_rounded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tile Rounded"},"watermarking_config":{"anyOf":[{"$ref":"#/components/schemas/WatermarkingConfiguration"},{"type":"null"}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSort"},{"type":"null"}]},"watermark_proxies":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Watermark Proxies","readOnly":true}},"type":"object","required":["watermark_proxies"],"title":"CollectionSettings"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"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":{"/collections/{collection_id}":{"put":{"tags":["collections"],"summary":"Update a collection","description":"Update a collection","operationId":"updateCollection","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to be updated"},"description":"The id of the collection to be updated"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectionRequest"}}}},"responses":{"200":{"description":"The updated collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete a collection

> Delete a collection

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"/collections/{collection_id}":{"delete":{"tags":["collections"],"summary":"Delete a collection","description":"Delete a collection","operationId":"deleteCollection","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to be deleted"},"description":"The id of the collection to be deleted"}],"responses":{"200":{"description":"True if the collection was deleted, false if it was not found","content":{"application/json":{"schema":{"type":"boolean"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get an MRSS feed for a collection

> Return an MRSS (Media RSS) feed for a collection.\
> \
> This endpoint is intended for public consumption and only returns data when\
> the collection's public link visibility is enabled. If the collection is\
> not public or is expired, a 404 is returned. If the collection is\
> password-protected and the password is incorrect, a 403 is returned.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"/collections/{collection_id}/mrss":{"get":{"tags":["collections"],"summary":"Get an MRSS feed for a collection","description":"Return an MRSS (Media RSS) feed for a collection.\n\nThis endpoint is intended for public consumption and only returns data when\nthe collection's public link visibility is enabled. If the collection is\nnot public or is expired, a 404 is returned. If the collection is\npassword-protected and the password is incorrect, a 403 is returned.","operationId":"getCollectionMrss","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id"},"description":"ID of the collection. List a drive's collections with `GET /collections`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"title":"Page number","description":"1-indexed page of assets in the collection to return.","default":1},"description":"1-indexed page of assets in the collection to return."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Page size","description":"Maximum number of assets to include in the MRSS feed.","default":20},"description":"Maximum number of assets to include in the MRSS feed."}],"responses":{"200":{"description":"An MRSS XML feed for the public collection","content":{"application/rss+xml":{"schema":{"type":"string"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Duplicate a collection

> Duplicate a collection with configurable options for what to include.\
> \
> \- include\_files: Copy asset references and directory paths\
> \- include\_styling: Copy icon, icon\_type, background\_image, and settings\
> \- include\_permissions: Copy is\_public\_enabled, allowed\_actions, expiration\_date (NOT password)

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"DuplicateCollectionRequest":{"properties":{"include_files":{"type":"boolean","title":"Include files","description":"Whether to copy asset references and directory paths","default":true},"include_styling":{"type":"boolean","title":"Include styling","description":"Whether to copy icon, background, and view settings","default":true},"include_permissions":{"type":"boolean","title":"Include permissions","description":"Whether to copy public link settings (excluding password)","default":false}},"type":"object","title":"DuplicateCollectionRequest"},"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":{"/collections/{collection_id}/duplicate":{"post":{"tags":["collections"],"summary":"Duplicate a collection","description":"Duplicate a collection with configurable options for what to include.\n\n- include_files: Copy asset references and directory paths\n- include_styling: Copy icon, icon_type, background_image, and settings\n- include_permissions: Copy is_public_enabled, allowed_actions, expiration_date (NOT password)","operationId":"duplicateCollection","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to duplicate"},"description":"The id of the collection to duplicate"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateCollectionRequest"}}}},"responses":{"200":{"description":"The id of the duplicated collection","content":{"application/json":{"schema":{"type":"string","format":"uuid"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Add assets to a collection

> Add assets to a collection, if they are in the same drive.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"AddAssetsToCollectionRequest":{"properties":{"asset_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"The asset ids to add to the collection","description":"The ids of the assets to add to the collection","default":[]},"directory_paths":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"The directory paths","description":"Add all assets under these paths to the collection","default":[]}},"type":"object","title":"AddAssetsToCollectionRequest"},"CollectionDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserDTOBase"},{"type":"null"}]},"is_public_enabled":{"type":"boolean","title":"Is Public Enabled"},"allowed_actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Allowed Actions"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"settings":{"$ref":"#/components/schemas/CollectionSettings-Output"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"icon":{"type":"string","title":"Icon"},"icon_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"background_image":{"type":"string","title":"Background Image"},"background_image_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]},"is_expired":{"type":"boolean","title":"Is Expired","default":false},"password_protected":{"type":"boolean","title":"Password Protected"},"expiration_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expiration Date"}},"type":"object","required":["id","name","description","drive_id","created_by","is_public_enabled","allowed_actions","invite_id","settings","icon_type","icon","background_image","password_protected"],"title":"CollectionDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"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."},"CollectionSettings-Output":{"properties":{"view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"},"thumbnail_view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail View"},"thumbnail_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Size"},"card_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Card Size"},"metadata_attribute_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata Attribute Ids"},"tile_rounded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tile Rounded"},"watermarking_config":{"anyOf":[{"$ref":"#/components/schemas/WatermarkingConfiguration"},{"type":"null"}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSort"},{"type":"null"}]},"watermark_proxies":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Watermark Proxies","readOnly":true}},"type":"object","required":["watermark_proxies"],"title":"CollectionSettings"},"WatermarkingConfiguration":{"properties":{"mode":{"$ref":"#/components/schemas/WatermarkingMode"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"position":{"anyOf":[{"$ref":"#/components/schemas/WatermarkPosition"},{"type":"null"}]},"font_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Font Size"}},"type":"object","required":["mode"],"title":"WatermarkingConfiguration","description":"Typed configuration for text-based watermarking and transcoder options."},"WatermarkingMode":{"type":"string","enum":["session","text"],"title":"WatermarkingMode"},"WatermarkPosition":{"type":"string","enum":["top_left","top_center","top_right","center","bottom_left","bottom_center","bottom_right"],"title":"WatermarkPosition"},"CollectionSettingSort":{"properties":{"attribute":{"type":"string","title":"Attribute"},"direction":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSortDirection"},{"type":"null"}]}},"type":"object","required":["attribute"],"title":"CollectionSettingSort"},"CollectionSettingSortDirection":{"type":"string","enum":["ASC","DESC","CUSTOM"],"title":"CollectionSettingSortDirection"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"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":{"/collections/{collection_id}/assets":{"post":{"tags":["collections"],"summary":"Add assets to a collection","description":"Add assets to a collection, if they are in the same drive.","operationId":"addAssetsToCollection","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to add assets to"},"description":"The id of the collection to add assets to"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAssetsToCollectionRequest"}}}},"responses":{"200":{"description":"The updated collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Remove assets from a collection

> Remove assets from a collection

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"DeleteCollectionAssetsRequest":{"properties":{"asset_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"The asset ids","description":"The ids of the assets to remove from the collection"}},"type":"object","required":["asset_ids"],"title":"DeleteCollectionAssetsRequest"},"CollectionDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserDTOBase"},{"type":"null"}]},"is_public_enabled":{"type":"boolean","title":"Is Public Enabled"},"allowed_actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Allowed Actions"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"settings":{"$ref":"#/components/schemas/CollectionSettings-Output"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"icon":{"type":"string","title":"Icon"},"icon_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"background_image":{"type":"string","title":"Background Image"},"background_image_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]},"is_expired":{"type":"boolean","title":"Is Expired","default":false},"password_protected":{"type":"boolean","title":"Password Protected"},"expiration_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expiration Date"}},"type":"object","required":["id","name","description","drive_id","created_by","is_public_enabled","allowed_actions","invite_id","settings","icon_type","icon","background_image","password_protected"],"title":"CollectionDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"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."},"CollectionSettings-Output":{"properties":{"view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"},"thumbnail_view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail View"},"thumbnail_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Size"},"card_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Card Size"},"metadata_attribute_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata Attribute Ids"},"tile_rounded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tile Rounded"},"watermarking_config":{"anyOf":[{"$ref":"#/components/schemas/WatermarkingConfiguration"},{"type":"null"}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSort"},{"type":"null"}]},"watermark_proxies":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Watermark Proxies","readOnly":true}},"type":"object","required":["watermark_proxies"],"title":"CollectionSettings"},"WatermarkingConfiguration":{"properties":{"mode":{"$ref":"#/components/schemas/WatermarkingMode"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"position":{"anyOf":[{"$ref":"#/components/schemas/WatermarkPosition"},{"type":"null"}]},"font_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Font Size"}},"type":"object","required":["mode"],"title":"WatermarkingConfiguration","description":"Typed configuration for text-based watermarking and transcoder options."},"WatermarkingMode":{"type":"string","enum":["session","text"],"title":"WatermarkingMode"},"WatermarkPosition":{"type":"string","enum":["top_left","top_center","top_right","center","bottom_left","bottom_center","bottom_right"],"title":"WatermarkPosition"},"CollectionSettingSort":{"properties":{"attribute":{"type":"string","title":"Attribute"},"direction":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSortDirection"},{"type":"null"}]}},"type":"object","required":["attribute"],"title":"CollectionSettingSort"},"CollectionSettingSortDirection":{"type":"string","enum":["ASC","DESC","CUSTOM"],"title":"CollectionSettingSortDirection"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"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":{"/collections/{collection_id}/assets":{"delete":{"tags":["collections"],"summary":"Remove assets from a collection","description":"Remove assets from a collection","operationId":"deleteCollectionAssets","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to remove a file from"},"description":"The id of the collection to remove a file from"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteCollectionAssetsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Move an asset to a new position in the collection

> Move a single asset to a new position in the collection.\
> Only updates the assets affected by the move.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"UpdateCollectionAssetOrderRequest":{"properties":{"asset_id":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to move"},"new_order":{"type":"integer","title":"The new position","description":"The new position for the asset (1-indexed)"}},"type":"object","required":["asset_id","new_order"],"title":"UpdateCollectionAssetOrderRequest"},"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":{"/collections/{collection_id}/assets/order":{"post":{"tags":["collections"],"summary":"Move an asset to a new position in the collection","description":"Move a single asset to a new position in the collection.\nOnly updates the assets affected by the move.","operationId":"updateCollectionAssetOrder","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection whose asset order will be updated"},"description":"The id of the collection whose asset order will be updated"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectionAssetOrderRequest"}}}},"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 directory paths from a collection

> Get the directory paths from a collection

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"/collections/{collection_id}/directories":{"get":{"tags":["collections"],"summary":"Get directory paths from a collection","description":"Get the directory paths from a collection","operationId":"getDirectoriesFromCollection","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to get directory paths from"},"description":"The id of the collection to get directory paths from"},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Optional query to filter directory paths"},"description":"Optional query to filter directory paths"}],"responses":{"200":{"description":"The directory paths included in the collection","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Add directory paths to a collection

> Add directory paths to a collection.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"AddDirectoriesToCollectionRequest":{"properties":{"directory_paths":{"items":{"type":"string"},"type":"array","title":"The directory paths to add to the collection","description":"The paths of the directories to add to the collection"}},"type":"object","required":["directory_paths"],"title":"AddDirectoriesToCollectionRequest"},"CollectionDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserDTOBase"},{"type":"null"}]},"is_public_enabled":{"type":"boolean","title":"Is Public Enabled"},"allowed_actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Allowed Actions"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"settings":{"$ref":"#/components/schemas/CollectionSettings-Output"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"icon":{"type":"string","title":"Icon"},"icon_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"background_image":{"type":"string","title":"Background Image"},"background_image_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]},"is_expired":{"type":"boolean","title":"Is Expired","default":false},"password_protected":{"type":"boolean","title":"Password Protected"},"expiration_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expiration Date"}},"type":"object","required":["id","name","description","drive_id","created_by","is_public_enabled","allowed_actions","invite_id","settings","icon_type","icon","background_image","password_protected"],"title":"CollectionDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"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."},"CollectionSettings-Output":{"properties":{"view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"},"thumbnail_view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail View"},"thumbnail_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Size"},"card_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Card Size"},"metadata_attribute_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata Attribute Ids"},"tile_rounded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tile Rounded"},"watermarking_config":{"anyOf":[{"$ref":"#/components/schemas/WatermarkingConfiguration"},{"type":"null"}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSort"},{"type":"null"}]},"watermark_proxies":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Watermark Proxies","readOnly":true}},"type":"object","required":["watermark_proxies"],"title":"CollectionSettings"},"WatermarkingConfiguration":{"properties":{"mode":{"$ref":"#/components/schemas/WatermarkingMode"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"position":{"anyOf":[{"$ref":"#/components/schemas/WatermarkPosition"},{"type":"null"}]},"font_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Font Size"}},"type":"object","required":["mode"],"title":"WatermarkingConfiguration","description":"Typed configuration for text-based watermarking and transcoder options."},"WatermarkingMode":{"type":"string","enum":["session","text"],"title":"WatermarkingMode"},"WatermarkPosition":{"type":"string","enum":["top_left","top_center","top_right","center","bottom_left","bottom_center","bottom_right"],"title":"WatermarkPosition"},"CollectionSettingSort":{"properties":{"attribute":{"type":"string","title":"Attribute"},"direction":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSortDirection"},{"type":"null"}]}},"type":"object","required":["attribute"],"title":"CollectionSettingSort"},"CollectionSettingSortDirection":{"type":"string","enum":["ASC","DESC","CUSTOM"],"title":"CollectionSettingSortDirection"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"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":{"/collections/{collection_id}/directories":{"post":{"tags":["collections"],"summary":"Add directory paths to a collection","description":"Add directory paths to a collection.","operationId":"addDirectoriesToCollection","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to add directory paths to"},"description":"The id of the collection to add directory paths to"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddDirectoriesToCollectionRequest"}}}},"responses":{"200":{"description":"The updated collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Remove directory paths from a collection

> Remove directory paths from a collection

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"DeleteCollectionDirectoriesRequest":{"properties":{"directory_paths":{"items":{"type":"string"},"type":"array","title":"The directory paths","description":"The paths of the directories to remove from the collection"}},"type":"object","required":["directory_paths"],"title":"DeleteCollectionDirectoriesRequest"},"CollectionDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/UserDTOBase"},{"type":"null"}]},"is_public_enabled":{"type":"boolean","title":"Is Public Enabled"},"allowed_actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Allowed Actions"},"invite_id":{"type":"string","format":"uuid","title":"Invite Id"},"settings":{"$ref":"#/components/schemas/CollectionSettings-Output"},"icon_type":{"$ref":"#/components/schemas/DriveIconType"},"icon":{"type":"string","title":"Icon"},"icon_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"background_image":{"type":"string","title":"Background Image"},"background_image_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]},"is_expired":{"type":"boolean","title":"Is Expired","default":false},"password_protected":{"type":"boolean","title":"Password Protected"},"expiration_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expiration Date"}},"type":"object","required":["id","name","description","drive_id","created_by","is_public_enabled","allowed_actions","invite_id","settings","icon_type","icon","background_image","password_protected"],"title":"CollectionDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"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."},"CollectionSettings-Output":{"properties":{"view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"},"thumbnail_view":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail View"},"thumbnail_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Size"},"card_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Card Size"},"metadata_attribute_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Metadata Attribute Ids"},"tile_rounded":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tile Rounded"},"watermarking_config":{"anyOf":[{"$ref":"#/components/schemas/WatermarkingConfiguration"},{"type":"null"}]},"sort":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSort"},{"type":"null"}]},"watermark_proxies":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Watermark Proxies","readOnly":true}},"type":"object","required":["watermark_proxies"],"title":"CollectionSettings"},"WatermarkingConfiguration":{"properties":{"mode":{"$ref":"#/components/schemas/WatermarkingMode"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"position":{"anyOf":[{"$ref":"#/components/schemas/WatermarkPosition"},{"type":"null"}]},"font_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Font Size"}},"type":"object","required":["mode"],"title":"WatermarkingConfiguration","description":"Typed configuration for text-based watermarking and transcoder options."},"WatermarkingMode":{"type":"string","enum":["session","text"],"title":"WatermarkingMode"},"WatermarkPosition":{"type":"string","enum":["top_left","top_center","top_right","center","bottom_left","bottom_center","bottom_right"],"title":"WatermarkPosition"},"CollectionSettingSort":{"properties":{"attribute":{"type":"string","title":"Attribute"},"direction":{"anyOf":[{"$ref":"#/components/schemas/CollectionSettingSortDirection"},{"type":"null"}]}},"type":"object","required":["attribute"],"title":"CollectionSettingSort"},"CollectionSettingSortDirection":{"type":"string","enum":["ASC","DESC","CUSTOM"],"title":"CollectionSettingSortDirection"},"DriveIconType":{"type":"string","enum":["color","emoji","attachment"],"title":"DriveIconType"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"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":{"/collections/{collection_id}/directories":{"delete":{"tags":["collections"],"summary":"Remove directory paths from a collection","description":"Remove directory paths from a collection","operationId":"deleteCollectionDirectories","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to remove directory paths from"},"description":"The id of the collection to remove directory paths from"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteCollectionDirectoriesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Start the upload process for a collection attachment

> Start the upload process for a collection attachment

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"StartCollectionAttachmentUploadRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to create the attachment for"},"name":{"type":"string","title":"The name of the attachment","description":"The name of the attachment to be created"},"mime_type":{"type":"string","title":"The mime type of the attachment","description":"The mime type of the attachment to be created"},"size":{"type":"integer","title":"The size of the attachment","description":"The size of the attachment to be created"},"upload_for":{"type":"string","enum":["icon","background"],"title":"What the upload is for","description":"What the upload is for ('icon' or 'background')"}},"type":"object","required":["drive_id","name","mime_type","size","upload_for"],"title":"StartCollectionAttachmentUploadRequest"},"AttachmentToUploadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"upload_url":{"type":"string","title":"Upload Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","upload_url"],"title":"AttachmentToUploadDTO"},"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":{"/collections/{collection_id}/attachments":{"post":{"tags":["collections"],"summary":"Start the upload process for a collection attachment","description":"Start the upload process for a collection attachment","operationId":"startCollectionAttachmentUpload","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to create the attachment for"},"description":"The id of the collection to create the attachment for"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartCollectionAttachmentUploadRequest"}}}},"responses":{"200":{"description":"The id of the created user collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentToUploadDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Mark the upload of a collection attachment as complete

> Mark the upload of a collection attachment as complete

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"collections","description":"A collection is a hand-picked set of assets, like a playlist, that can span\nfolders. Collections can be shared publicly with their own link settings.\n\nSee [Collections and share links](https://academy.shade.inc/developers/using-the-api/collections-and-share-links) for a walkthrough.\n\n* Create one with `POST /collections`, then add assets with\n  `POST /collections/{collection_id}/assets`.\n* To list a collection's assets, call `POST /search` with `collection_id`.\n* `POST /collections/{collection_id}/directories` adds whole folders."}],"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":{"MarkCollectionAttachmentUploadedRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to mark the attachment uploaded for"}},"type":"object","required":["drive_id"],"title":"MarkCollectionAttachmentUploadedRequest"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"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":{"/collections/{collection_id}/attachments/{attachment_id}":{"post":{"tags":["collections"],"summary":"Mark the upload of a collection attachment as complete","description":"Mark the upload of a collection attachment as complete","operationId":"markCollectionAttachmentUploaded","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The collection id","description":"The id of the collection to mark the attachment uploaded for"},"description":"The id of the collection to mark the attachment uploaded for"},{"name":"attachment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The attachment id","description":"The id of the attachment to mark as uploaded"},"description":"The id of the attachment to mark as uploaded"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkCollectionAttachmentUploadedRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"}}}},"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/organize/collections.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.
