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

# Assets

An asset is a file Shade has indexed. Its `AssetDTO` includes the file's path, type, size, AI-generated details, custom metadata, previews, and the state of each processing job.

* Look up an asset by path with `GET /assets/path`, or by ID with `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.
* Get a signed download URL with `GET /assets/{asset_id}/download`. Use `origin_type=SOURCE` for the original file or `PROXY` for the lightweight preview video.
* `*_job_state` fields show when previews, proxies, transcription, and AI indexing finish. Rather than polling, subscribe to the [webhook](https://academy.shade.inc/developers/webhooks) events.

See [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets).

## Get duplicate file groups for a drive

> Returns groups of files that have identical content (same hash) within a drive

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"DuplicateAssetDTO":{"properties":{"hash":{"type":"string","title":"Hash"},"type":{"$ref":"#/components/schemas/AssetType"},"path":{"type":"string","title":"Path"},"count":{"type":"integer","title":"Count"},"preview_image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview Image"}},"type":"object","required":["hash","type","path","count"],"title":"DuplicateAssetDTO"},"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":{"/assets/duplicates":{"get":{"tags":["assets"],"summary":"Get duplicate file groups for a drive","description":"Returns groups of files that have identical content (same hash) within a drive","operationId":"getDuplicateGroups","parameters":[{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to search for duplicates"},"description":"The id of the drive to search for duplicates"},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page number","description":"The page to query","default":0},"description":"The page to query"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit per page","description":"The limit that is fetched per page","default":100},"description":"The limit that is fetched per page"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DuplicateAssetDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get all duplicate assets for a specific hash

> Returns all assets that share the same content hash (duplicates of each other)

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"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":{"/assets/duplicates/{content_hash}":{"get":{"tags":["assets"],"summary":"Get all duplicate assets for a specific hash","description":"Returns all assets that share the same content hash (duplicates of each other)","operationId":"getDuplicateAssetsByHash","parameters":[{"name":"content_hash","in":"path","required":true,"schema":{"type":"string","title":"Content Hash"}},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to search within"},"description":"The id of the drive to search within"},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page number","description":"The page to query","default":0},"description":"The page to query"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit per page","description":"The limit that is fetched per page","default":100},"description":"The limit that is fetched per page"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AssetDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get all preview images for an asset with signed urls

> Get all preview images for an asset, including signed URLs for each preview image.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"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":{"/assets/{asset_id}/previews":{"get":{"tags":["assets"],"summary":"Get all preview images for an asset with signed urls","description":"Get all preview images for an asset, including signed URLs for each preview image.","operationId":"getAssetPreviews","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PreviewDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /assets/{asset\_id}/clip

> Clip a video between two timestamps (redirects to edge transcoder)

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"/assets/{asset_id}/clip":{"get":{"tags":["assets"],"summary":"Clip a video between two timestamps (redirects to edge transcoder)","operationId":"clipVideo","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"},{"name":"start_time","in":"query","required":true,"schema":{"type":"number","title":"Start time in seconds","description":"The start time of the clip in seconds"},"description":"The start time of the clip in seconds"},{"name":"end_time","in":"query","required":true,"schema":{"type":"number","title":"End time in seconds","description":"The end time of the clip in seconds"},"description":"The end time of the clip in seconds"}],"responses":{"302":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get a signed download URL for an asset's data

> Get a signed download URL for an asset's data based on the origin type

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"OriginType":{"type":"string","enum":["SOURCE","PROXY"],"title":"OriginType","description":"Which copy of an asset's data to fetch."},"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":{"/assets/{asset_id}/download":{"get":{"tags":["assets"],"summary":"Get a signed download URL for an asset's data","description":"Get a signed download URL for an asset's data based on the origin type","operationId":"getAssetDownloadUrl","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"},{"name":"origin_type","in":"query","required":true,"schema":{"$ref":"#/components/schemas/OriginType","title":"The origin type","description":"The origin of the asset's data to fetch"},"description":"The origin of the asset's data to fetch"},{"name":"name","in":"query","required":false,"schema":{"type":"string","title":"The name of the file to download as","description":"The name of the file to download as"},"description":"The name of the file to download as"},{"name":"download","in":"query","required":false,"schema":{"type":"boolean","title":"Indicator for downloading vs viewing the file","description":"Whether to download the file or view it inline","default":true},"description":"Whether to download the file or view it inline"}],"responses":{"200":{"description":"A signed download URL","content":{"application/json":{"schema":{"type":"string"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /assets/{asset\_id}/source

> Get an asset source by redirecting to the signed url

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"/assets/{asset_id}/source":{"get":{"tags":["assets"],"summary":"Get an asset source by redirecting to the signed url","operationId":"getAssetSource","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"},{"name":"name","in":"query","required":false,"schema":{"type":"string","title":"The name of the file to download as","description":"The name of the file to download as"},"description":"The name of the file to download as"},{"name":"authorization","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The authorization token"},"description":"Your API key, for clients that can't set headers, such as an `<img>` or `<video>` tag. Prefer the `Authorization` header, since URLs end up in logs and browser history."},{"name":"shade-collection-id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Collection ID","description":"The collection id to authorize against, if not provided will use the default collection for the user."},"description":"The collection id to authorize against, if not provided will use the default collection for the user."}],"responses":{"302":{"description":"A signed download URL"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get an asset from its path

> Get an asset from its path

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"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":{"/assets/path":{"get":{"tags":["assets"],"summary":"Get an asset from its path","description":"Get an asset from its path","operationId":"getAssetFromPath","parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string","title":"The path"},"description":"Path of the file or folder, starting with the drive ID, for example `/7b1e4d2c-5a6f-4e8b-9c3d-2f1a0b9c8d7e/Project/Interviews/A001.mov`."},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"responses":{"200":{"description":"The asset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /assets/stack/{stack\_id}

> Get all assets for a stack

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"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":{"/assets/stack/{stack_id}":{"get":{"tags":["assets"],"summary":"Get all assets for a stack","operationId":"getAssetStack","parameters":[{"name":"stack_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The stack id","description":"The id of the stack to retrieve assets for"},"description":"The id of the stack to retrieve assets for"},{"name":"directory_path","in":"query","required":true,"schema":{"type":"string","title":"The directory path","description":"The directory path that the stack is located under"},"description":"The directory path that the stack is located under"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this stack is in"},"description":"The id of the drive this stack is in"}],"responses":{"200":{"description":"A list of assets for the stack","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AssetDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create a new stack from a list of assets

> Create a new stack from a list of assets

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"CreateAssetStackRequest":{"properties":{"asset_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Asset IDs","description":"List of asset IDs to create a stack from"},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive these assets are in"}},"type":"object","required":["asset_ids","drive_id"],"title":"CreateAssetStackRequest"},"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":{"/assets/stack":{"post":{"tags":["assets"],"summary":"Create a new stack from a list of assets","description":"Create a new stack from a list of assets","operationId":"createAssetStack","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetStackRequest"}}}},"responses":{"200":{"description":"The ID of the created stack","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 an asset to a stack

> Add an asset to a stack

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"/assets/{asset_id}/stack":{"post":{"tags":["assets"],"summary":"Add an asset to a stack","description":"Add an asset to a stack","operationId":"addAssetToStack","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to add to the stack"},"description":"The id of the asset to add to the stack"},{"name":"target_asset_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The target asset id","description":"The id of an asset in the stack to add the asset to"},"description":"The id of an asset in the stack to add the asset to"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"responses":{"200":{"description":"The stack number of the added asset","content":{"application/json":{"schema":{"type":"integer"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Remove an asset from its stack

> Remove an asset from its stack

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"/assets/{asset_id}/stack":{"delete":{"tags":["assets"],"summary":"Remove an asset from its stack","description":"Remove an asset from its stack","operationId":"removeAssetFromStack","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to remove from its stack"},"description":"The id of the asset to remove from its stack"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Move an asset to a new position within its stack

> Move an asset to a new position within its stack

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"/assets/{asset_id}/stack/move":{"put":{"tags":["assets"],"summary":"Move an asset to a new position within its stack","description":"Move an asset to a new position within its stack","operationId":"moveAssetInStack","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to move within the stack"},"description":"The id of the asset to move within the stack"},{"name":"new_stack_number","in":"query","required":true,"schema":{"type":"integer","title":"New stack number","description":"The new stack number position for the asset"},"description":"The new stack number position for the asset"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"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 an asset

> Get an asset

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"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":{"/assets/{asset_id}":{"get":{"tags":["assets"],"summary":"Get an asset","description":"Get an asset","operationId":"getAsset","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"responses":{"200":{"description":"The asset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /assets/{asset\_id}/custom-thumbnail

> Get Custom Thumbnail Download

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"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":{"/assets/{asset_id}/custom-thumbnail":{"get":{"tags":["assets"],"summary":"Get Custom Thumbnail Download","operationId":"getCustomThumbnailDownload","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"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"}}}}}}}}}
```

## POST /assets/{asset\_id}/custom-thumbnail

> Set Custom Thumbnail

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"SetCustomThumbnailRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"attachment_token":{"type":"string","title":"Attachment tokens","description":"JWT tokens for attachments to link to this thumbnail"}},"type":"object","title":"SetCustomThumbnailRequest"},"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":{"/assets/{asset_id}/custom-thumbnail":{"post":{"tags":["assets"],"summary":"Set Custom Thumbnail","operationId":"setCustomThumbnail","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetCustomThumbnailRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## DELETE /assets/{asset\_id}/custom-thumbnail

> Reset Custom Thumbnail

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"/assets/{asset_id}/custom-thumbnail":{"delete":{"tags":["assets"],"summary":"Reset Custom Thumbnail","operationId":"resetCustomThumbnail","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this attachment is in"},"description":"The id of the drive this attachment is in"}],"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 /previews/url/{preview\_id}

> Get a preview by its id. Returns as a redirect to the signed url.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"/previews/url/{preview_id}":{"get":{"tags":["assets"],"summary":"Get a preview by its id. Returns as a redirect to the signed url.","operationId":"getPreviewUrl","parameters":[{"name":"preview_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Preview Id"}},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The name of the preview to get","description":"The name of the preview to get"},"description":"The name of the preview to get"},{"name":"authorization","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The authorization token"},"description":"Your API key, for clients that can't set headers, such as an `<img>` or `<video>` tag. Prefer the `Authorization` header, since URLs end up in logs and browser history."}],"responses":{"302":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /proxies/{proxy\_id}

> Get a proxy by id by redirecting to the signed url

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"assets","description":"An asset is a file Shade has indexed. Its `AssetDTO` includes the file's\npath, type, size, AI-generated details, custom metadata, previews, and the\nstate of each processing job.\n\n* Look up an asset by path with `GET /assets/path`, or by ID with\n  `GET /assets/{asset_id}`. Search, webhooks, and collections all return asset IDs.\n* Get a signed download URL with `GET /assets/{asset_id}/download`. Use\n  `origin_type=SOURCE` for the original file or `PROXY` for the\n  lightweight preview video.\n* `*_job_state` fields show when previews, proxies, transcription, and AI\n  indexing finish. Rather than polling, subscribe to the\n  [webhook](https://academy.shade.inc/developers/webhooks) events.\n\nSee [Working with assets](https://academy.shade.inc/developers/using-the-api/working-with-assets)."}],"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":{"/proxies/{proxy_id}":{"get":{"tags":["assets"],"summary":"Get a proxy by id by redirecting to the signed url","operationId":"getProxyUrl","parameters":[{"name":"proxy_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Proxy Id"}},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The name of the proxy to get","description":"The name of the proxy to get"},"description":"The name of the proxy to get"},{"name":"authorization","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The authorization token"},"description":"Your API key, for clients that can't set headers, such as an `<img>` or `<video>` tag. Prefer the `Authorization` header, since URLs end up in logs and browser history."},{"name":"shade-collection-id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Collection ID","description":"The collection id to authorize against, if not provided will use the default collection for the user."},"description":"The collection id to authorize against, if not provided will use the default collection for the user."}],"responses":{"200":{"description":"A watermarked HLS playlist, when watermarking applies","content":{"audio/mpegurl":{"schema":{"type":"string"}}}},"302":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

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

```
GET https://academy.shade.inc/developers/files-and-assets/assets.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.
