> 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/search-and-ai/search.md).

# Search

`POST /search` is the main way to find and list assets in a drive. It combines Shade's AI search with filters on file properties and metadata.

* `query` is a natural-language search. Leave it out to list everything that matches the filters.
* `filters` narrows results by path, type, dates, size, collection, or any metadata attribute. Every filter has an `id`, a `clause`, and `options`.
* `sort` takes a field such as `created` or `-updated` (descending). When `sort` is set, `query` is ignored.
* Page through results with `limit` and `page`.

See [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets) for every filter and clause.

## Simple search for file names folders, collections, individuals, and views

> Unified simple search endpoint that searches across assets, folders, collections, individuals, and views.\
> \
> This endpoint provides a lightweight search that:\
> \- Searches assets by name\
> \- Searches folders by directory name\
> \- Searches collections by name\
> \- Searches individuals (face groups) by name\
> \- Searches dynamic views by name\
> \- Returns a unified list ranked by match quality (exact > prefix > contains > similarity)\
> \
> Unlike the main search endpoint, this does not perform AI-powered search or\
> semantic search. It's designed for fast, simple name-based lookups across\
> all searchable entities in the drive.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"SimpleSearchRequest":{"properties":{"query":{"type":"string","title":"Search query","description":"The query to search for across all entity types."},"drive_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The drive id","description":"The id of a single drive to search in. Use drive_ids for multi-drive search."},"drive_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Drive IDs","description":"List of drive IDs to search across. Takes precedence over drive_id if both provided."},"limit":{"type":"integer","title":"Limit","description":"The maximum total number of results to return across all entity types. Defaults to 50.","default":50},"offset":{"type":"integer","title":"Offset","description":"The offset for pagination. Defaults to 0.","default":0},"entity_types":{"anyOf":[{"items":{"$ref":"#/components/schemas/SearchEntity"},"type":"array"},{"type":"null"}],"title":"Entity types","description":"Optional list of entity types to search. If not provided, searches everything except workspace members, which must be asked for and need every drive to be in one workspace."},"created_after":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created after","description":"Only include results created at or after this timestamp."},"created_before":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created before","description":"Only include results created at or before this timestamp."}},"type":"object","required":["query"],"title":"SimpleSearchRequest"},"SearchEntity":{"type":"string","enum":["asset","folder","collection","individual","view","user"],"title":"SearchEntity","description":"Entity types that can be searched in simple search."},"AssetSearchResultDTO":{"properties":{"entity_type":{"type":"string","const":"asset","title":"Entity Type","default":"asset"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"name":{"type":"string","title":"Name"},"path":{"type":"string","title":"Path"},"asset":{"$ref":"#/components/schemas/AssetSimpleSearchDTO"}},"type":"object","required":["entity_id","drive_id","name","path","asset"],"title":"AssetSearchResultDTO"},"AssetSimpleSearchDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"path":{"type":"string","title":"Path"},"name":{"type":"string","title":"Name"},"extension":{"type":"string","title":"Extension"},"type":{"$ref":"#/components/schemas/AssetType"},"size_bytes":{"type":"integer","title":"Size Bytes"},"created":{"type":"string","format":"date-time","title":"Created"},"updated":{"type":"string","format":"date-time","title":"Updated"},"stack_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Stack Id"},"stack_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stack Number"},"is_fs_draft_blob":{"type":"boolean","title":"Is Fs Draft Blob"},"is_fs_null_blob":{"type":"boolean","title":"Is Fs Null Blob"},"system_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"System Metadata","default":{}},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata","default":{}},"preview_images":{"items":{"$ref":"#/components/schemas/PreviewDTO"},"type":"array","title":"Preview Images","default":[]},"custom_thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}]},"proxy":{"anyOf":[{"$ref":"#/components/schemas/ProxyDTO"},{"type":"null"}]}},"type":"object","required":["id","drive_id","path","name","extension","type","size_bytes","created","updated","is_fs_draft_blob","is_fs_null_blob"],"title":"AssetSimpleSearchDTO","description":"Lean asset DTO for search-result preview. Skips full_data + job_state fields,\nso the search enrichment doesn't need to load those relationships."},"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"},"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"},"ProxyDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"}},"type":"object","required":["id"],"title":"ProxyDTO"},"FolderSearchResultDTO":{"properties":{"entity_type":{"type":"string","const":"folder","title":"Entity Type","default":"folder"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"name":{"type":"string","title":"Name"},"path":{"type":"string","title":"Path"}},"type":"object","required":["drive_id","name","path"],"title":"FolderSearchResultDTO"},"CollectionSearchResultDTO":{"properties":{"entity_type":{"type":"string","const":"collection","title":"Entity Type","default":"collection"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"icon_type":{"anyOf":[{"$ref":"#/components/schemas/DriveIconType"},{"type":"null"}]},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"},"background_image":{"type":"string","title":"Background Image","default":""},"background_image_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]}},"type":"object","required":["entity_id","drive_id","name"],"title":"CollectionSearchResultDTO"},"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"},"IndividualSearchResultDTO":{"properties":{"entity_type":{"type":"string","const":"individual","title":"Entity Type","default":"individual"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]}},"type":"object","required":["entity_id","drive_id","name"],"title":"IndividualSearchResultDTO"},"ViewSearchResultDTO":{"properties":{"entity_type":{"type":"string","const":"view","title":"Entity Type","default":"view"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"name":{"type":"string","title":"Name"},"icon_type":{"anyOf":[{"$ref":"#/components/schemas/DriveIconType"},{"type":"null"}]},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"}},"type":"object","required":["entity_id","drive_id","name"],"title":"ViewSearchResultDTO"},"UserSearchResultDTO":{"properties":{"entity_type":{"type":"string","const":"user","title":"Entity Type","default":"user"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"}},"type":"object","required":["entity_id","name","email"],"title":"UserSearchResultDTO"},"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":{"/search/simple":{"post":{"tags":["search"],"summary":"Simple search for file names folders, collections, individuals, and views","description":"Unified simple search endpoint that searches across assets, folders, collections, individuals, and views.\n\nThis endpoint provides a lightweight search that:\n- Searches assets by name\n- Searches folders by directory name\n- Searches collections by name\n- Searches individuals (face groups) by name\n- Searches dynamic views by name\n- Returns a unified list ranked by match quality (exact > prefix > contains > similarity)\n\nUnlike the main search endpoint, this does not perform AI-powered search or\nsemantic search. It's designed for fast, simple name-based lookups across\nall searchable entities in the drive.","operationId":"simpleSearch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleSearchRequest"}}}},"responses":{"200":{"description":"Unified search results ranked by relevance","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/AssetSearchResultDTO"},{"$ref":"#/components/schemas/FolderSearchResultDTO"},{"$ref":"#/components/schemas/CollectionSearchResultDTO"},{"$ref":"#/components/schemas/IndividualSearchResultDTO"},{"$ref":"#/components/schemas/ViewSearchResultDTO"},{"$ref":"#/components/schemas/UserSearchResultDTO"}],"discriminator":{"propertyName":"entity_type","mapping":{"asset":"#/components/schemas/AssetSearchResultDTO","folder":"#/components/schemas/FolderSearchResultDTO","collection":"#/components/schemas/CollectionSearchResultDTO","individual":"#/components/schemas/IndividualSearchResultDTO","view":"#/components/schemas/ViewSearchResultDTO","user":"#/components/schemas/UserSearchResultDTO"}}}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Track a search result selection for personalized ranking

> Track when a user selects a search result to improve future search rankings.\
> \
> This endpoint records which search results users click on, allowing the system\
> to boost frequently selected results to the top of future searches for the same query.\
> \
> Requires authentication.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"TrackSearchSelectionRequest":{"properties":{"query":{"type":"string","title":"Query","description":"The search query that was performed"},"entity_type":{"$ref":"#/components/schemas/SearchEntity","description":"Type of entity selected"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"ID of the selected entity (null for folders)"},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path","description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},"drive_id":{"type":"string","format":"uuid","title":"Drive Id","description":"Drive where the search occurred"}},"type":"object","required":["query","entity_type","drive_id"],"title":"TrackSearchSelectionRequest"},"SearchEntity":{"type":"string","enum":["asset","folder","collection","individual","view","user"],"title":"SearchEntity","description":"Entity types that can be searched in simple search."},"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":{"/search/simple/ranking":{"post":{"tags":["search"],"summary":"Track a search result selection for personalized ranking","description":"Track when a user selects a search result to improve future search rankings.\n\nThis endpoint records which search results users click on, allowing the system\nto boost frequently selected results to the top of future searches for the same query.\n\nRequires authentication.","operationId":"trackSearchSelection","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackSearchSelectionRequest"}}}},"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"}}}}}}}}}
```

## Reset personalized search rankings

> Reset personalized search ranking data for a user.\
> \
> If a query is provided, only rankings for that specific query are reset.\
> Otherwise, all search rankings for the user in the specified drive are reset.\
> \
> Requires authentication.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"ResetSearchRankingRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"Drive Id","description":"Drive to reset rankings for"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Optional specific query to reset. If not provided, resets all queries."}},"type":"object","required":["drive_id"],"title":"ResetSearchRankingRequest"},"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":{"/search/simple/ranking/reset":{"post":{"tags":["search"],"summary":"Reset personalized search rankings","description":"Reset personalized search ranking data for a user.\n\nIf a query is provided, only rankings for that specific query are reset.\nOtherwise, all search rankings for the user in the specified drive are reset.\n\nRequires authentication.","operationId":"resetSearchRanking","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetSearchRankingRequest"}}}},"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 recent unique search queries for the current user

> Get the most recent unique search queries for the current user.\
> \
> Returns queries ordered by the most recent selection time across any result\
> for that query. Useful for showing search history or suggested searches.\
> \
> Requires authentication.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"RecentSearchQueryDTO":{"properties":{"query":{"type":"string","title":"Query"},"last_selected_at":{"type":"string","format":"date-time","title":"Last Selected At"}},"type":"object","required":["query","last_selected_at"],"title":"RecentSearchQueryDTO"},"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":{"/search/simple/queries/recent":{"get":{"tags":["search"],"summary":"Get recent unique search queries for the current user","description":"Get the most recent unique search queries for the current user.\n\nReturns queries ordered by the most recent selection time across any result\nfor that query. Useful for showing search history or suggested searches.\n\nRequires authentication.","operationId":"getRecentSearchQueries","parameters":[{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to get recent queries for"},"description":"The id of the drive to get recent queries for"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","title":"Limit","description":"Maximum number of recent queries to return. Defaults to 10.","default":10},"description":"Maximum number of recent queries to return. Defaults to 10."}],"responses":{"200":{"description":"Recent unique queries, most recently selected first","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RecentSearchQueryDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /search/ai-filters

> Generate Ai Filters

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"AIFilterRequest":{"properties":{"prompt":{"type":"string","maxLength":1000,"title":"Prompt"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"}},"type":"object","required":["prompt","drive_id"],"title":"AIFilterRequest"},"AIFilterResponseDTO":{"properties":{"filters":{"items":{"$ref":"#/components/schemas/AddedFilterForStorage"},"type":"array","title":"Filters"}},"type":"object","required":["filters"],"title":"AIFilterResponseDTO"},"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"},"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":{"/search/ai-filters":{"post":{"tags":["search"],"summary":"Generate Ai Filters","operationId":"generateAiFilters","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIFilterRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIFilterResponseDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Search for assets. Note: This request is idempotent

> Search for assets in the database. This is the primary search function on assets.\
> \
> If collection\_id is provided, the search is restricted to that collection.\
> Otherwise, the search is performed on the entire drive.\
> \
> This route should not be called for searching on a public path - use /search/files instead.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"SearchRequest":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search query","description":"A natural-language query, matched with Shade's AI search. Leave it out to return everything that matches `filters`. Ignored when `sort` is set."},"filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/AddedFilterForSearch"},"type":"array"},{"type":"null"}],"title":"Filters","description":"Filters that results must match. Each filter has an `id` (a field such as `path`, `type`, `name`,\n`extension`, `created`, `updated`, `size_bytes`, `collection`, or `individual`, or a metadata\nattribute ID), a `clause` such as `is`, `is under`, or `after`, and a list of `options`."},"similar_asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Similar asset id","description":"The id of the asset to find similar assets to."},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort order","description":"Field to sort by, such as `name`, `created`, `updated`, `size_bytes`, or a metadata attribute ID. Prefix with `-` for descending order, for example `-created`. Results are sorted by `name` when there's no `query` or `sort`."},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Offset","description":"The offset of results to return. Input either this or 'page'. Defaults to 0 if neither are inputted."},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page","description":"Zero-based page number. Use `page` or `offset`, not both."},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"The maximum number of assets to return. Defaults to 100.","default":100},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive we want to search on."},"return_only_attrs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Return only these attributes","description":"The attributes that you want to return. If not provided, all attributes will be returned. This is limited, and not all attributes that exist on AssetDTO will work.","default":[]},"collection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The collection id","description":"The id of the collection to search within."},"attribute_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Metadata attribute ids","description":"When provided, asset DTOs only carry custom-metadata values for these attribute ids. Filters and sorts still resolve against the full drive schema. Omit to return all custom metadata (legacy)."}},"type":"object","required":["drive_id"],"title":"SearchRequest"},"AddedFilterForSearch":{"properties":{"id":{"title":"Id","description":"The field to filter on, such as `path`, `type`, `name`, `extension`, `created`, `updated`, `size_bytes`, `collection`, or `individual`, or a metadata attribute ID."},"options":{"items":{"type":"string"},"type":"array","title":"Options","description":"Values to compare against. Paths start with the drive ID, types are `AssetType` values such as\n`VIDEO`, dates are ISO 8601 strings, and select attributes take option IDs."},"clause":{"$ref":"#/components/schemas/FilterClauseVal"}},"type":"object","required":["id","options","clause"],"title":"AddedFilterForSearch"},"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"},"AssetDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"path":{"type":"string","title":"Path"},"name":{"type":"string","title":"Name"},"extension":{"type":"string","title":"Extension"},"updated":{"type":"string","format":"date-time","title":"Updated"},"created":{"type":"string","format":"date-time","title":"Created"},"type":{"$ref":"#/components/schemas/AssetType"},"size_bytes":{"type":"integer","title":"Size Bytes"},"stack_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Stack Id"},"stack_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stack Number"},"is_fs_draft_blob":{"type":"boolean","title":"Is Fs Draft Blob"},"is_fs_null_blob":{"type":"boolean","title":"Is Fs Null Blob"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"ai_indexed":{"type":"boolean","title":"Ai Indexed"},"system_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"System Metadata","default":{}},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata","default":{}},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"palette":{"items":{"items":{"type":"integer"},"type":"array"},"type":"array","title":"Palette"},"ocr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ocr"},"transcription_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Transcription Id"},"faces_present":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Faces Present"},"content_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Content Length"},"comment_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Comment Count"},"preview_job_state":{"$ref":"#/components/schemas/JobState"},"metadata_job_state":{"$ref":"#/components/schemas/JobState"},"custom_metadata_job_state":{"$ref":"#/components/schemas/JobState"},"core_vision_job_state":{"$ref":"#/components/schemas/JobState"},"color_palette_job_state":{"$ref":"#/components/schemas/JobState"},"core_audio_job_state":{"$ref":"#/components/schemas/JobState"},"audio_job_state":{"$ref":"#/components/schemas/JobState"},"facial_recognition_job_state":{"$ref":"#/components/schemas/JobState"},"proxy_job_state":{"$ref":"#/components/schemas/JobState"},"audio_proxy_job_state":{"$ref":"#/components/schemas/JobState"},"transcription_job_state":{"$ref":"#/components/schemas/JobState"},"scrub_sheet_job_state":{"$ref":"#/components/schemas/JobState"},"objects":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Objects"},"texture_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Texture Data"},"integration_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Integration Data"},"preview_images":{"items":{"$ref":"#/components/schemas/PreviewDTO"},"type":"array","title":"Preview Images"},"custom_thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}]},"proxy":{"anyOf":[{"$ref":"#/components/schemas/ProxyDTO"},{"type":"null"}]},"audio_proxy":{"anyOf":[{"$ref":"#/components/schemas/ProxyDTO"},{"type":"null"}]},"scrub_sheet":{"anyOf":[{"$ref":"#/components/schemas/ScrubSheetDTO"},{"type":"null"}]},"grid_scrub_sheet":{"anyOf":[{"$ref":"#/components/schemas/ScrubSheetDTO"},{"type":"null"}]}},"type":"object","required":["id","drive_id","path","name","extension","updated","created","type","size_bytes","is_fs_draft_blob","is_fs_null_blob","ai_indexed","palette","preview_job_state","metadata_job_state","custom_metadata_job_state","core_vision_job_state","color_palette_job_state","core_audio_job_state","facial_recognition_job_state","proxy_job_state","audio_proxy_job_state","transcription_job_state","scrub_sheet_job_state","preview_images"],"title":"AssetDTO","description":"Full asset DTO with relationship fields that require eager loading."},"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"},"JobState":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","COMPLETED","FAILED","INSUFFICIENT_CREDITS"],"title":"JobState","description":"The state of a processing job on an asset, such as previews or transcription."},"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"},"ProxyDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"}},"type":"object","required":["id"],"title":"ProxyDTO"},"ScrubSheetDTO":{"properties":{"preview_width":{"type":"integer","title":"Preview Width"},"preview_height":{"type":"integer","title":"Preview Height"},"columns":{"type":"integer","title":"Columns"},"rows":{"type":"integer","title":"Rows"},"interval":{"type":"number","title":"Interval"},"total_frames":{"type":"integer","title":"Total Frames"},"scrub_sheets":{"items":{"type":"string"},"type":"array","title":"Scrub Sheets"}},"type":"object","required":["preview_width","preview_height","columns","rows","interval","total_frames","scrub_sheets"],"title":"ScrubSheetDTO"},"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":{"/search":{"post":{"tags":["search"],"summary":"Search for assets. Note: This request is idempotent","description":"Search for assets in the database. This is the primary search function on assets.\n\nIf collection_id is provided, the search is restricted to that collection.\nOtherwise, the search is performed on the entire drive.\n\nThis route should not be called for searching on a public path - use /search/files instead.","operationId":"search","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"A list of matching assets","content":{"application/json":{"schema":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/AssetDTO"},{"type":"object","additionalProperties":true}]}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Chunk enabled version of search above

> Search for subclips using columnar search engine. Returns assets with their associated chunks.\
> \
> If collection\_id is provided, the search is restricted to that collection.\
> Otherwise, the search is performed on the entire drive.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"SearchSubclipRequest":{"properties":{"query":{"type":"string","title":"Search query","description":"The query to search for subclips."},"filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/AddedFilterForSearch"},"type":"array"},{"type":"null"}],"title":"Filters","description":"The filters that you want to apply to your search."},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive we want to search on."},"database_signals":{"items":{"type":"string"},"type":"array","title":"Database signals","description":"The database column signals to search through.","default":[]},"signal_weights":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Signal weights","description":"Weights for each database signal (e.g., {'video_chunks': 1.0, 'document_chunks': 0.8}). Default is 1.0 for all."},"search_modes":{"anyOf":[{"additionalProperties":{"additionalProperties":{"type":"boolean"},"type":"object"},"type":"object"},{"type":"null"}],"title":"Search modes","description":"Search modes per signal. Each signal can have 'vector' and 'fulltext' modes enabled/disabled. E.g., {'video_chunks': {'vector': True, 'fulltext': False}, 'document_chunks': {'vector': True, 'fulltext': True}}. Default enables both modes where available."},"merge_chunks":{"type":"boolean","title":"Merge chunks","description":"Whether to merge overlapping/adjacent chunks within the same asset. Disable to see individual chunk segments.","default":true},"expansion_threshold":{"type":"number","maximum":1,"minimum":0,"title":"Expansion threshold","description":"Controls how far to expand from score peaks when merging (0.0-1.0). Converted to drop_ratio = 1 - threshold. 0.7 = include chunks >= 30% of peak score (default), 0.5 = include chunks >= 50% of peak (tighter segments), 0.9 = include chunks >= 10% of peak (larger segments).","default":0.7},"hot_chunk_threshold":{"type":"number","maximum":1,"minimum":0,"title":"Hot chunk threshold","description":"Filter chunks to only those scoring >= this ratio of the best chunk's score (0.0-1.0). 0.0 = no filtering (show all), 0.5 = only chunks >= 50% of best, 0.7 = only chunks >= 70% of best. Use to show only the most relevant 'hot' chunks.","default":0.7},"video_score_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Video score threshold","description":"Minimum score threshold for video/audio chunks. Chunks below this score are filtered out. Suggested: 0.03"},"document_score_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Document score threshold","description":"Minimum score threshold for document/transcription chunks. Chunks below this score are filtered out. Suggested: 0.35"},"image_score_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Image score threshold","description":"Minimum score threshold for image chunks. Chunks below this score are filtered out. Suggested: 0.02"},"relevance_sensitivity":{"type":"number","maximum":1,"minimum":0,"title":"Relevance sensitivity","description":"Dynamic cutoff sensitivity for filtering irrelevant assets (0.0-1.0). Uses gap detection to find natural score boundaries between relevant and irrelevant results. 0.0 = no filtering (show all), 0.5 = moderate (cut at 50%+ score drops), 1.0 = aggressive (cut at 20%+ drops).","default":0},"max_vector_distance":{"type":"number","maximum":1,"minimum":0,"title":"Max vector distance","description":"Maximum cosine distance threshold for vector search (0.0-1.0). Chunks with distance >= this threshold are filtered out early, improving query performance. Lower values = stricter filtering (faster but may miss results). 0.8 is recommended for most use cases.","default":0.8},"collection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The collection id","description":"The id of the collection to search within."}},"type":"object","required":["query","drive_id"],"title":"SearchSubclipRequest"},"AddedFilterForSearch":{"properties":{"id":{"title":"Id","description":"The field to filter on, such as `path`, `type`, `name`, `extension`, `created`, `updated`, `size_bytes`, `collection`, or `individual`, or a metadata attribute ID."},"options":{"items":{"type":"string"},"type":"array","title":"Options","description":"Values to compare against. Paths start with the drive ID, types are `AssetType` values such as\n`VIDEO`, dates are ISO 8601 strings, and select attributes take option IDs."},"clause":{"$ref":"#/components/schemas/FilterClauseVal"}},"type":"object","required":["id","options","clause"],"title":"AddedFilterForSearch"},"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"},"ChunkedSearchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/AssetWithChunkDTO"},"type":"array","title":"Results"},"debug":{"anyOf":[{"$ref":"#/components/schemas/SearchDebugInfo"},{"type":"null"}]}},"type":"object","required":["results"],"title":"ChunkedSearchResponse","description":"Response wrapper for chunked search including debug info."},"AssetWithChunkDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"path":{"type":"string","title":"Path"},"name":{"type":"string","title":"Name"},"extension":{"type":"string","title":"Extension"},"updated":{"type":"string","format":"date-time","title":"Updated"},"created":{"type":"string","format":"date-time","title":"Created"},"type":{"$ref":"#/components/schemas/AssetType"},"size_bytes":{"type":"integer","title":"Size Bytes"},"stack_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Stack Id"},"stack_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stack Number"},"is_fs_draft_blob":{"type":"boolean","title":"Is Fs Draft Blob"},"is_fs_null_blob":{"type":"boolean","title":"Is Fs Null Blob"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"ai_indexed":{"type":"boolean","title":"Ai Indexed"},"system_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"System Metadata","default":{}},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata","default":{}},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"palette":{"items":{"items":{"type":"integer"},"type":"array"},"type":"array","title":"Palette"},"ocr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ocr"},"transcription_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Transcription Id"},"faces_present":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Faces Present"},"content_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Content Length"},"comment_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Comment Count"},"preview_job_state":{"$ref":"#/components/schemas/JobState"},"metadata_job_state":{"$ref":"#/components/schemas/JobState"},"custom_metadata_job_state":{"$ref":"#/components/schemas/JobState"},"core_vision_job_state":{"$ref":"#/components/schemas/JobState"},"color_palette_job_state":{"$ref":"#/components/schemas/JobState"},"core_audio_job_state":{"$ref":"#/components/schemas/JobState"},"audio_job_state":{"$ref":"#/components/schemas/JobState"},"facial_recognition_job_state":{"$ref":"#/components/schemas/JobState"},"proxy_job_state":{"$ref":"#/components/schemas/JobState"},"audio_proxy_job_state":{"$ref":"#/components/schemas/JobState"},"transcription_job_state":{"$ref":"#/components/schemas/JobState"},"scrub_sheet_job_state":{"$ref":"#/components/schemas/JobState"},"objects":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Objects"},"texture_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Texture Data"},"integration_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Integration Data"},"preview_images":{"items":{"$ref":"#/components/schemas/PreviewDTO"},"type":"array","title":"Preview Images"},"custom_thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}]},"proxy":{"anyOf":[{"$ref":"#/components/schemas/ProxyDTO"},{"type":"null"}]},"audio_proxy":{"anyOf":[{"$ref":"#/components/schemas/ProxyDTO"},{"type":"null"}]},"scrub_sheet":{"anyOf":[{"$ref":"#/components/schemas/ScrubSheetDTO"},{"type":"null"}]},"grid_scrub_sheet":{"anyOf":[{"$ref":"#/components/schemas/ScrubSheetDTO"},{"type":"null"}]},"relevant_chunks":{"items":{},"type":"array","title":"Relevant Chunks","default":[]}},"type":"object","required":["id","drive_id","path","name","extension","updated","created","type","size_bytes","is_fs_draft_blob","is_fs_null_blob","ai_indexed","palette","preview_job_state","metadata_job_state","custom_metadata_job_state","core_vision_job_state","color_palette_job_state","core_audio_job_state","facial_recognition_job_state","proxy_job_state","audio_proxy_job_state","transcription_job_state","scrub_sheet_job_state","preview_images"],"title":"AssetWithChunkDTO","description":"Asset DTO for chunk search results - includes preview images and proxy URLs."},"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"},"JobState":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","COMPLETED","FAILED","INSUFFICIENT_CREDITS"],"title":"JobState","description":"The state of a processing job on an asset, such as previews or transcription."},"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"},"ProxyDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"}},"type":"object","required":["id"],"title":"ProxyDTO"},"ScrubSheetDTO":{"properties":{"preview_width":{"type":"integer","title":"Preview Width"},"preview_height":{"type":"integer","title":"Preview Height"},"columns":{"type":"integer","title":"Columns"},"rows":{"type":"integer","title":"Rows"},"interval":{"type":"number","title":"Interval"},"total_frames":{"type":"integer","title":"Total Frames"},"scrub_sheets":{"items":{"type":"string"},"type":"array","title":"Scrub Sheets"}},"type":"object","required":["preview_width","preview_height","columns","rows","interval","total_frames","scrub_sheets"],"title":"ScrubSheetDTO"},"SearchDebugInfo":{"properties":{"sql_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sql Query"},"pg_planning_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pg Planning Ms"},"pg_execution_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pg Execution Ms"}},"type":"object","title":"SearchDebugInfo","description":"Debug info for search queries, only returned for allowed users."},"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":{"/search/chunked":{"post":{"tags":["search"],"summary":"Chunk enabled version of search above","description":"Search for subclips using columnar search engine. Returns assets with their associated chunks.\n\nIf collection_id is provided, the search is restricted to that collection.\nOtherwise, the search is performed on the entire drive.","operationId":"searchSubclip","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchSubclipRequest"}}}},"responses":{"200":{"description":"A list of matching assets with chunks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChunkedSearchResponse"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get the folders in a folder

> Get all content in a folder (non-indexed and indexed)

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"/search/folders":{"get":{"tags":["search"],"summary":"Get the folders in a folder","description":"Get all content in a folder (non-indexed and indexed)","operationId":"listFolders","parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string","title":"The directory path","format":"path"},"description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search query","description":"The query to search for. If not provided, all folder contents will be returned."},"description":"The query to search for. If not provided, all folder contents will be returned."},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Offset","description":"The offset of results to return. Input either this or 'page'."},"description":"The offset of results to return. Input either this or 'page'."},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page number","description":"The page to query. Input either this or 'offset'."},"description":"The page to query. Input either this or 'offset'."},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit per page","description":"The limit that is fetched per page"},"description":"The limit that is fetched per page"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive we want to add user to"},"description":"The id of the drive we want to add user to"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"path"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get the folders in a folder (POST)

> Get all content in a folder (POST variant for sandboxed environments\
> where query params cannot contain path separators).

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"ListFoldersPostRequest":{"properties":{"path":{"type":"string","format":"path","title":"The directory path","description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search query"},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Offset"},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page number"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit per page"},"drive_id":{"type":"string","format":"uuid","title":"The drive id"}},"type":"object","required":["path","drive_id"],"title":"ListFoldersPostRequest"},"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":{"/search/folders":{"post":{"tags":["search"],"summary":"Get the folders in a folder (POST)","description":"Get all content in a folder (POST variant for sandboxed environments\nwhere query params cannot contain path separators).","operationId":"listFoldersPost","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListFoldersPostRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"path"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get the files in a folder

> Get all files in a folder. This performs a "search" with a filter on the path, and auths on public paths.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"SearchFilesInFolderRequest":{"properties":{"path":{"type":"string","format":"path","title":"The directory path","description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},"recursive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recursive search","description":"Whether or not to do a recursive search on the directory","default":false},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search query","description":"The query to search for. If not provided, all folder contents will be returned."},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Offset","description":"The offset of results to return. Input either this or 'page'. Defaults to 0 if neither are inputted."},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page number","description":"The page to query. Input either this or 'offset'. Defaults to 0 if neither are inputted."},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit per page","description":"The limit that is fetched per page. Defaults to 100","default":100},"filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/AddedFilterForSearch"},"type":"array"},{"type":"null"}],"title":"Filters","description":"The filters that you want to apply to your search."},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort order","description":"A field name, optionally prefixed by the - sign to specify a descending order."},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive we want to add user to"},"return_only_attrs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Return only these attributes","description":"The attributes that you want to return. If not provided, all attributes will be returned. This is limited, and not all attributes that exist on AssetDTO will work.","default":[]},"collection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The collection id","description":"The id of the collection (used for custom sort when browsing folders within a collection)."},"attribute_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Metadata attribute ids","description":"When provided, asset DTOs only carry custom-metadata values for these attribute ids. Filters and sorts still resolve against the full drive schema. Omit to return all custom metadata (legacy)."}},"type":"object","required":["path","drive_id"],"title":"SearchFilesInFolderRequest"},"AddedFilterForSearch":{"properties":{"id":{"title":"Id","description":"The field to filter on, such as `path`, `type`, `name`, `extension`, `created`, `updated`, `size_bytes`, `collection`, or `individual`, or a metadata attribute ID."},"options":{"items":{"type":"string"},"type":"array","title":"Options","description":"Values to compare against. Paths start with the drive ID, types are `AssetType` values such as\n`VIDEO`, dates are ISO 8601 strings, and select attributes take option IDs."},"clause":{"$ref":"#/components/schemas/FilterClauseVal"}},"type":"object","required":["id","options","clause"],"title":"AddedFilterForSearch"},"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"},"AssetDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"path":{"type":"string","title":"Path"},"name":{"type":"string","title":"Name"},"extension":{"type":"string","title":"Extension"},"updated":{"type":"string","format":"date-time","title":"Updated"},"created":{"type":"string","format":"date-time","title":"Created"},"type":{"$ref":"#/components/schemas/AssetType"},"size_bytes":{"type":"integer","title":"Size Bytes"},"stack_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Stack Id"},"stack_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stack Number"},"is_fs_draft_blob":{"type":"boolean","title":"Is Fs Draft Blob"},"is_fs_null_blob":{"type":"boolean","title":"Is Fs Null Blob"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"ai_indexed":{"type":"boolean","title":"Ai Indexed"},"system_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"System Metadata","default":{}},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata","default":{}},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"palette":{"items":{"items":{"type":"integer"},"type":"array"},"type":"array","title":"Palette"},"ocr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ocr"},"transcription_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Transcription Id"},"faces_present":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Faces Present"},"content_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Content Length"},"comment_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Comment Count"},"preview_job_state":{"$ref":"#/components/schemas/JobState"},"metadata_job_state":{"$ref":"#/components/schemas/JobState"},"custom_metadata_job_state":{"$ref":"#/components/schemas/JobState"},"core_vision_job_state":{"$ref":"#/components/schemas/JobState"},"color_palette_job_state":{"$ref":"#/components/schemas/JobState"},"core_audio_job_state":{"$ref":"#/components/schemas/JobState"},"audio_job_state":{"$ref":"#/components/schemas/JobState"},"facial_recognition_job_state":{"$ref":"#/components/schemas/JobState"},"proxy_job_state":{"$ref":"#/components/schemas/JobState"},"audio_proxy_job_state":{"$ref":"#/components/schemas/JobState"},"transcription_job_state":{"$ref":"#/components/schemas/JobState"},"scrub_sheet_job_state":{"$ref":"#/components/schemas/JobState"},"objects":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Objects"},"texture_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Texture Data"},"integration_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Integration Data"},"preview_images":{"items":{"$ref":"#/components/schemas/PreviewDTO"},"type":"array","title":"Preview Images"},"custom_thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}]},"proxy":{"anyOf":[{"$ref":"#/components/schemas/ProxyDTO"},{"type":"null"}]},"audio_proxy":{"anyOf":[{"$ref":"#/components/schemas/ProxyDTO"},{"type":"null"}]},"scrub_sheet":{"anyOf":[{"$ref":"#/components/schemas/ScrubSheetDTO"},{"type":"null"}]},"grid_scrub_sheet":{"anyOf":[{"$ref":"#/components/schemas/ScrubSheetDTO"},{"type":"null"}]}},"type":"object","required":["id","drive_id","path","name","extension","updated","created","type","size_bytes","is_fs_draft_blob","is_fs_null_blob","ai_indexed","palette","preview_job_state","metadata_job_state","custom_metadata_job_state","core_vision_job_state","color_palette_job_state","core_audio_job_state","facial_recognition_job_state","proxy_job_state","audio_proxy_job_state","transcription_job_state","scrub_sheet_job_state","preview_images"],"title":"AssetDTO","description":"Full asset DTO with relationship fields that require eager loading."},"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"},"JobState":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","COMPLETED","FAILED","INSUFFICIENT_CREDITS"],"title":"JobState","description":"The state of a processing job on an asset, such as previews or transcription."},"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"},"ProxyDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"}},"type":"object","required":["id"],"title":"ProxyDTO"},"ScrubSheetDTO":{"properties":{"preview_width":{"type":"integer","title":"Preview Width"},"preview_height":{"type":"integer","title":"Preview Height"},"columns":{"type":"integer","title":"Columns"},"rows":{"type":"integer","title":"Rows"},"interval":{"type":"number","title":"Interval"},"total_frames":{"type":"integer","title":"Total Frames"},"scrub_sheets":{"items":{"type":"string"},"type":"array","title":"Scrub Sheets"}},"type":"object","required":["preview_width","preview_height","columns","rows","interval","total_frames","scrub_sheets"],"title":"ScrubSheetDTO"},"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":{"/search/files":{"post":{"tags":["search"],"summary":"Get the files in a folder","description":"Get all files in a folder. This performs a \"search\" with a filter on the path, and auths on public paths.","operationId":"searchFilesInFolder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchFilesInFolderRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/AssetDTO"},{"type":"object","additionalProperties":true}]}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Export search results

> Export search results to a file. The file is returned as a downloadable response.\
> \
> If collection\_id is provided, the search is restricted to that collection.\
> If path is provided, the search is restricted to that path (includes public path).\
> Otherwise, the search is performed on the entire drive.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"ExportFormat":{"type":"string","enum":["csv","tsv","txt","ale","premiere","davinci","avid"],"title":"ExportFormat"},"ExportSearchRequest":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search query","description":"The query to search for."},"filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/AddedFilterForSearch"},"type":"array"},{"type":"null"}],"title":"Filters","description":"The filters that you want to apply to your search."},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort order","description":"A field name, optionally prefixed by the - sign to specify a descending order."},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Offset","description":"The offset of results to return. Input either this or 'page'. Defaults to 0 if neither are inputted."},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page number","description":"The page to query. Input either this or 'offset'. Defaults to 0 if neither are inputted."},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit per page","description":"The limit that is fetched per page. Defaults to 100","default":100},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive we want to search on."},"collection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The collection id","description":"The id of the collection to search within."},"path":{"anyOf":[{"type":"string","format":"path"},{"type":"null"}],"title":"The directory path","description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},"recursive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Recursive search","description":"Whether or not to do a recursive search on the directory","default":false},"metadata_attribute_ids":{"items":{"type":"string"},"type":"array","title":"Attributes","description":"List of attribute IDs that should be returned (these are the columns in the export)"},"os":{"anyOf":[{"$ref":"#/components/schemas/OperatingSystem"},{"type":"null"}],"title":"The operating system","description":"The operating system that the exported file will be used on."}},"type":"object","required":["drive_id","metadata_attribute_ids"],"title":"ExportSearchRequest"},"AddedFilterForSearch":{"properties":{"id":{"title":"Id","description":"The field to filter on, such as `path`, `type`, `name`, `extension`, `created`, `updated`, `size_bytes`, `collection`, or `individual`, or a metadata attribute ID."},"options":{"items":{"type":"string"},"type":"array","title":"Options","description":"Values to compare against. Paths start with the drive ID, types are `AssetType` values such as\n`VIDEO`, dates are ISO 8601 strings, and select attributes take option IDs."},"clause":{"$ref":"#/components/schemas/FilterClauseVal"}},"type":"object","required":["id","options","clause"],"title":"AddedFilterForSearch"},"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"},"OperatingSystem":{"type":"string","enum":["Windows","Linux","Debian","Fedora","Darwin"],"title":"OperatingSystem","description":"Operating System Enum from the result of platform.system()"},"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":{"/search/exports/{export_format}":{"post":{"tags":["search"],"summary":"Export search results","description":"Export search results to a file. The file is returned as a downloadable response.\n\nIf collection_id is provided, the search is restricted to that collection.\nIf path is provided, the search is restricted to that path (includes public path).\nOtherwise, the search is performed on the entire drive.","operationId":"exportSearch","parameters":[{"name":"export_format","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ExportFormat","title":"The format","description":"The format that you want to export the search results in."},"description":"The format that you want to export the search results in."},{"name":"timezone","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The timezone to be exported to (ex: 'America/New_York')"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportSearchRequest"}}}},"responses":{"200":{"description":"A downloadable file","content":{"application/octet-stream":{"schema":{"type":"string"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Sign download URLs for assets picked by id or by search

> One row per asset, in input or search order, with a signed URL or an \`\`error\`\`.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"search","description":"`POST /search` is the main way to find and list assets in a drive. It\ncombines Shade's AI search with filters on file properties and metadata.\n\n* `query` is a natural-language search. Leave it out to list everything that\n  matches the filters.\n* `filters` narrows results by path, type, dates, size, collection, or any\n  metadata attribute. Every filter has an `id`, a `clause`, and `options`.\n* `sort` takes a field such as `created` or `-updated` (descending). When\n  `sort` is set, `query` is ignored.\n* Page through results with `limit` and `page`.\n\nSee [Searching and filtering assets](https://academy.shade.inc/developers/using-the-api/searching-and-filtering-assets)\nfor every filter and clause."}],"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":{"DownloadUrlsRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"origin_type":{"$ref":"#/components/schemas/OriginType"},"download":{"type":"boolean","title":"Download","default":true},"asset_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":1000},{"type":"null"}],"title":"Asset Ids"},"search":{"anyOf":[{"$ref":"#/components/schemas/DownloadSearch"},{"type":"null"}]}},"type":"object","required":["drive_id","origin_type"],"title":"DownloadUrlsRequest","description":"Pick assets by id or by search, never both."},"OriginType":{"type":"string","enum":["SOURCE","PROXY"],"title":"OriginType","description":"Which copy of an asset's data to fetch."},"DownloadSearch":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"},"filters":{"items":{"$ref":"#/components/schemas/AddedFilterForSearch"},"type":"array","title":"Filters","default":[]},"sort":{"type":"string","title":"Sort","default":""},"page":{"type":"integer","minimum":0,"title":"Page","default":0},"limit":{"type":"integer","maximum":1000,"minimum":1,"title":"Limit","default":1000},"collection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Collection Id"},"path":{"anyOf":[{"type":"string","format":"path"},{"type":"null"}],"title":"Path"},"recursive":{"type":"boolean","title":"Recursive","default":false},"share_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Share Id"}},"type":"object","title":"DownloadSearch","description":"Same scoping as ``/search/exports``: a collection, a path, or the whole drive."},"AddedFilterForSearch":{"properties":{"id":{"title":"Id","description":"The field to filter on, such as `path`, `type`, `name`, `extension`, `created`, `updated`, `size_bytes`, `collection`, or `individual`, or a metadata attribute ID."},"options":{"items":{"type":"string"},"type":"array","title":"Options","description":"Values to compare against. Paths start with the drive ID, types are `AssetType` values such as\n`VIDEO`, dates are ISO 8601 strings, and select attributes take option IDs."},"clause":{"$ref":"#/components/schemas/FilterClauseVal"}},"type":"object","required":["id","options","clause"],"title":"AddedFilterForSearch"},"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"},"AssetDownloadUrlDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"path":{"type":"string","title":"Path"},"type":{"$ref":"#/components/schemas/AssetType"},"size_bytes":{"type":"integer","title":"Size Bytes"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["id","path","type","size_bytes","url","error"],"title":"AssetDownloadUrlDTO","description":"One row of ``POST /search/download-urls``: enough to queue a client download."},"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"},"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":{"/search/download-urls":{"post":{"tags":["search"],"summary":"Sign download URLs for assets picked by id or by search","description":"One row per asset, in input or search order, with a signed URL or an ``error``.","operationId":"searchDownloadUrls","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadUrlsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AssetDownloadUrlDTO"}}}}},"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/search-and-ai/search.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.
