> For the complete documentation index, see [llms.txt](https://docs.pletor.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pletor.ai/documentation/api-reference/assets.md).

# Assets

Upload, retrieve, and download files used as inputs or generated as outputs.

## List Assets

> List assets with pagination and optional filtering.\
> \
> This endpoint returns a paginated list of assets belonging to your organization.\
> You can optionally filter by a specific list of asset IDs, by the agent that\
> produced them, and/or by the specific run that produced them.\
> \
> \*\*Primary Use Cases:\*\*\
> \- Browse all your assets with pagination\
> \- Retrieve specific assets using their IDs\
> \- Fetch every asset produced by a given agent across all its runs\
> \- Fetch every asset produced by a specific run\
> \- Verify the provenance of a known asset list (combine \`asset\_ids\` with\
>   \`agent\_id\` or \`run\_id\`)\
> \
> \*\*Pagination Parameters:\*\*\
> \- \`limit\`: Maximum number of items to return (default: 20, max: 100)\
> \- \`cursor\`: Cursor for pagination (optional)\
> \
> \*\*Filtering Parameters:\*\*\
> \- \`asset\_ids\`: Optional list of UUIDs to filter specific assets.\
> \- \`agent\_id\`: Optional agent UUID. Returns all assets produced by that agent\
>   across every run.\
> \- \`run\_id\`: Optional run UUID. Returns all assets produced by that single run.\
> \- All three filters compose as an AND. For example,\
> &#x20; \`?asset\_ids=\<id>\&agent\_id=\<agent>\` returns the asset only if it was\
> &#x20; produced by that agent; otherwise the response is empty.\
> \- \`agent\_id\` and \`run\_id\` only match assets that were produced by an agent\
> &#x20; run, so uploaded assets are excluded when either filter is set.\
> \
> \*\*Response:\*\*\
> Returns a \`CursorPaginatedResponse\` object containing:\
> \- \`data\`: List of \`AssetSummary\` objects. Each asset includes \`agent\_id\` and\
> &#x20; \`run\_id\` so you can correlate it back to the agent / run that produced it.\
> \- \`has\_more\`: Indicates if there are more results available\
> \- \`next\_cursor\`: Cursor for the next page\
> \
> \*\*Access Control:\*\*\
> \- Only assets belonging to your organization are returned\
> \- Assets not found or not accessible are silently excluded

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"assets","description":"Upload, retrieve, and download files used as inputs or generated as outputs."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"CursorPaginatedResponse_AssetSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AssetSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"CursorPaginatedResponse[AssetSummary]"},"AssetSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique asset identifier"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at upload, if any"},"asset_type":{"$ref":"#/components/schemas/AssetType","description":"Asset role: reference (input), intermediate, or output"},"media_type":{"$ref":"#/components/schemas/MediaType","description":"Media category: image, video, audio, or file"},"media_extension":{"$ref":"#/components/schemas/MediaExtension","description":"File extension: png, jpg, mp4, pdf, etc."},"visibility":{"$ref":"#/components/schemas/AssetVisibility","description":"Visibility level: private, public, or shared"},"bookmarked":{"type":"boolean","title":"Bookmarked","description":"Whether the asset is bookmarked","default":false},"archived":{"type":"boolean","title":"Archived","description":"Whether the asset is archived","default":false},"downloaded":{"type":"boolean","title":"Downloaded","description":"Whether the asset has been downloaded before","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the asset was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the asset was last modified"},"url":{"type":"string","title":"Url","description":"CDN URL for the asset (thumbnail/preview size)"},"large_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Large Url","description":"CDN URL for the full-resolution version"},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id","description":"ID of the agent that produced this asset. Null for uploaded assets."},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id","description":"ID of the run that produced this asset. Null for uploaded assets."}},"type":"object","required":["id","asset_type","media_type","media_extension","visibility","created_at","updated_at","url"],"title":"AssetSummary","description":"Summary of an asset for list views."},"AssetType":{"type":"string","enum":["reference","intermediate","output"],"title":"AssetType","description":"Classification of assets by their role in workflows."},"MediaType":{"type":"string","enum":["image","video","audio","file"],"title":"MediaType","description":"Primary media categories for assets."},"MediaExtension":{"type":"string","enum":["png","jpg","jpeg","svg","heic","heif","avif","webp","mp4","wav","mp3","mov","webm","pdf","docx","csv","txt","json","md","ttf","otf","woff","woff2"],"title":"MediaExtension"},"AssetVisibility":{"type":"string","enum":["public","shared","private"],"title":"AssetVisibility"},"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"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/":{"get":{"tags":["assets"],"summary":"List Assets","description":"List assets with pagination and optional filtering.\n\nThis endpoint returns a paginated list of assets belonging to your organization.\nYou can optionally filter by a specific list of asset IDs, by the agent that\nproduced them, and/or by the specific run that produced them.\n\n**Primary Use Cases:**\n- Browse all your assets with pagination\n- Retrieve specific assets using their IDs\n- Fetch every asset produced by a given agent across all its runs\n- Fetch every asset produced by a specific run\n- Verify the provenance of a known asset list (combine `asset_ids` with\n  `agent_id` or `run_id`)\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, max: 100)\n- `cursor`: Cursor for pagination (optional)\n\n**Filtering Parameters:**\n- `asset_ids`: Optional list of UUIDs to filter specific assets.\n- `agent_id`: Optional agent UUID. Returns all assets produced by that agent\n  across every run.\n- `run_id`: Optional run UUID. Returns all assets produced by that single run.\n- All three filters compose as an AND. For example,\n  `?asset_ids=<id>&agent_id=<agent>` returns the asset only if it was\n  produced by that agent; otherwise the response is empty.\n- `agent_id` and `run_id` only match assets that were produced by an agent\n  run, so uploaded assets are excluded when either filter is set.\n\n**Response:**\nReturns a `CursorPaginatedResponse` object containing:\n- `data`: List of `AssetSummary` objects. Each asset includes `agent_id` and\n  `run_id` so you can correlate it back to the agent / run that produced it.\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page\n\n**Access Control:**\n- Only assets belonging to your organization are returned\n- Assets not found or not accessible are silently excluded","operationId":"list_assets_assets__get","parameters":[{"name":"asset_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}],"description":"Restrict the result to this list of asset IDs. Combines with `agent_id` / `run_id` as an AND — an asset is only returned if it is in this list and matches every other filter.","title":"Asset Ids"},"description":"Restrict the result to this list of asset IDs. Combines with `agent_id` / `run_id` as an AND — an asset is only returned if it is in this list and matches every other filter."},{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Return only assets produced by this agent (across all its runs). Uploaded assets are never returned by this filter.","title":"Agent Id"},"description":"Return only assets produced by this agent (across all its runs). Uploaded assets are never returned by this filter."},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Return only assets produced by this specific run. Uploaded assets are never returned by this filter.","title":"Run Id"},"description":"Return only assets produced by this specific run. Uploaded assets are never returned by this filter."},{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Return the asset you uploaded with this reference id. Use after a 409 on upload to fetch the existing asset.","title":"External Id"},"description":"Return the asset you uploaded with this reference id. Use after a 409 on upload to fetch the existing asset."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return","default":20,"title":"Limit"},"description":"Maximum number of items to return"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination (from next_cursor)","title":"Cursor"},"description":"Cursor for pagination (from next_cursor)"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_AssetSummary_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Asset

> Retrieve complete metadata for a specific asset.\
> \
> This endpoint returns detailed information about an asset, including its metadata,\
> access URLs, and processing information. Use this when you need complete asset\
> details rather than just summary information.\
> \
> \*\*Parameters:\*\*\
> \- \`asset\_id\`: UUID of the asset to retrieve\
> \
> \*\*Response:\*\*\
> Returns a complete \`Asset\` object with all \`AssetSummary\` fields plus:\
> \- \`asset\_metadata\`: Dictionary with processing metadata and technical details\
> \- \`is\_flow\_output\_sample\`: Whether this asset is a sample from agent execution\
> \- \`blur\_hash\`: Hash for progressive image loading (images only)\
> \
> \*\*Access Control:\*\*\
> \- Asset must be owned by the authenticated user's organization, or\
> \- Asset must have "public" or "shared" visibility\
> \
> \*\*Errors:\*\*\
> \- 404: Asset not found or access denied

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"assets","description":"Upload, retrieve, and download files used as inputs or generated as outputs."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"Asset":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique asset identifier"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at upload, if any"},"asset_type":{"$ref":"#/components/schemas/AssetType","description":"Asset role: reference (input), intermediate, or output"},"media_type":{"$ref":"#/components/schemas/MediaType","description":"Media category: image, video, audio, or file"},"media_extension":{"$ref":"#/components/schemas/MediaExtension","description":"File extension: png, jpg, mp4, pdf, etc."},"visibility":{"$ref":"#/components/schemas/AssetVisibility","description":"Visibility level: private, public, or shared"},"bookmarked":{"type":"boolean","title":"Bookmarked","description":"Whether the asset is bookmarked","default":false},"archived":{"type":"boolean","title":"Archived","description":"Whether the asset is archived","default":false},"downloaded":{"type":"boolean","title":"Downloaded","description":"Whether the asset has been downloaded before","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the asset was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the asset was last modified"},"url":{"type":"string","title":"Url","description":"CDN URL for the asset (thumbnail/preview size)"},"large_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Large Url","description":"CDN URL for the full-resolution version"},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id","description":"ID of the agent that produced this asset. Null for uploaded assets."},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id","description":"ID of the run that produced this asset. Null for uploaded assets."},"asset_metadata":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"type":"object","title":"Asset Metadata","description":"Technical metadata: generation_model, aspect_ratio, duration, etc."},"is_flow_output_sample":{"type":"boolean","title":"Is Flow Output Sample","description":"Whether this asset is a sample output displayed on the agent card","default":false},"blur_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blur Hash","description":"BlurHash string for progressive image loading"}},"type":"object","required":["id","asset_type","media_type","media_extension","visibility","created_at","updated_at","url"],"title":"Asset","description":"Complete asset with all metadata."},"AssetType":{"type":"string","enum":["reference","intermediate","output"],"title":"AssetType","description":"Classification of assets by their role in workflows."},"MediaType":{"type":"string","enum":["image","video","audio","file"],"title":"MediaType","description":"Primary media categories for assets."},"MediaExtension":{"type":"string","enum":["png","jpg","jpeg","svg","heic","heif","avif","webp","mp4","wav","mp3","mov","webm","pdf","docx","csv","txt","json","md","ttf","otf","woff","woff2"],"title":"MediaExtension"},"AssetVisibility":{"type":"string","enum":["public","shared","private"],"title":"AssetVisibility"},"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"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}":{"get":{"tags":["assets"],"summary":"Get Asset","description":"Retrieve complete metadata for a specific asset.\n\nThis endpoint returns detailed information about an asset, including its metadata,\naccess URLs, and processing information. Use this when you need complete asset\ndetails rather than just summary information.\n\n**Parameters:**\n- `asset_id`: UUID of the asset to retrieve\n\n**Response:**\nReturns a complete `Asset` object with all `AssetSummary` fields plus:\n- `asset_metadata`: Dictionary with processing metadata and technical details\n- `is_flow_output_sample`: Whether this asset is a sample from agent execution\n- `blur_hash`: Hash for progressive image loading (images only)\n\n**Access Control:**\n- Asset must be owned by the authenticated user's organization, or\n- Asset must have \"public\" or \"shared\" visibility\n\n**Errors:**\n- 404: Asset not found or access denied","operationId":"get_asset_assets__asset_id__get","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Asset Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete Asset

> Soft-delete an asset.\
> \
> Marks the asset as deleted so it stops appearing in listings and can no\
> longer be downloaded. The underlying file is retained and the operation is\
> reversible by an administrator.\
> \
> \*\*Parameters:\*\*\
> \- \`asset\_id\`: UUID of the asset to delete\
> \
> \*\*Access Control:\*\*\
> \- Asset must be owned by the authenticated user's organization. Assets from\
> &#x20; other organizations are reported as \`404\` rather than deleted.\
> \
> \*\*Response:\*\*\
> \- \`204 No Content\` on success\
> \
> \*\*Errors:\*\*\
> \- 404: Asset not found or access denied\
> \- 410: Asset has already been deleted

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"assets","description":"Upload, retrieve, and download files used as inputs or generated as outputs."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"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"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}":{"delete":{"tags":["assets"],"summary":"Delete Asset","description":"Soft-delete an asset.\n\nMarks the asset as deleted so it stops appearing in listings and can no\nlonger be downloaded. The underlying file is retained and the operation is\nreversible by an administrator.\n\n**Parameters:**\n- `asset_id`: UUID of the asset to delete\n\n**Access Control:**\n- Asset must be owned by the authenticated user's organization. Assets from\n  other organizations are reported as `404` rather than deleted.\n\n**Response:**\n- `204 No Content` on success\n\n**Errors:**\n- 404: Asset not found or access denied\n- 410: Asset has already been deleted","operationId":"delete_asset_assets__asset_id__delete","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Asset Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Upload Asset

> Upload an asset file.\
> \
> This endpoint handles the complete asset upload process in a single request.\
> Simply send your file and get back a complete, ready-to-use asset.\
> \
> \*\*Request (multipart/form-data):\*\*\
> \- \`file\`: The file to upload (required)\
> \- \`visibility\`: Asset visibility level (default: "private")\
> &#x20; \- \`"private"\`: Only accessible by your organization\
> &#x20; \- \`"public"\`: Accessible by everyone\
> &#x20; \- \`"shared"\`: Accessible via shared links\
> \- \`filename\`: Optional custom display filename\
> \- \`external\_id\`: Optional client-supplied reference id (≤255 chars), unique\
> &#x20; per organization. Makes the upload safe to retry — reusing a key returns\
> &#x20; \`409\` instead of a duplicate asset; fetch the existing one via\
> &#x20; \`GET /assets?external\_id=\`.\
> \
> \*\*Supported File Types:\*\*\
> Images, videos, audio files, and documents (PNG, JPEG, MP4, PDF, etc.)\
> \
> \*\*Response:\*\*\
> Returns a complete \`Asset\` object ready to use immediately (with \`external\_id\`\
> echoed).\
> \
> \*\*Processing:\*\*\
> The asset is automatically processed in the background after upload,\
> including thumbnail generation and metadata extraction.\
> \
> \*\*Errors:\*\*\
> \- 400: Invalid or unsupported file type, or file cannot be read\
> \- 409: \`external\_id\` already used by another asset (don't retry; GET it instead)\
> \- 413: File too large\
> \- 500: Server error during upload or processing\
> \- 503: Storage service temporarily unavailable

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"assets","description":"Upload, retrieve, and download files used as inputs or generated as outputs."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"Body_upload_asset_assets_upload__post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"visibility":{"type":"string","title":"Visibility","description":"Asset visibility level","default":"private"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename","description":"Optional custom filename"},"external_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"External Id","description":"Optional client-supplied reference id, unique per organization. Reusing one returns 409; fetch the existing asset via GET /assets?external_id=. Makes the upload safe to retry without creating a duplicate."}},"type":"object","required":["file"],"title":"Body_upload_asset_assets_upload__post"},"Asset":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique asset identifier"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at upload, if any"},"asset_type":{"$ref":"#/components/schemas/AssetType","description":"Asset role: reference (input), intermediate, or output"},"media_type":{"$ref":"#/components/schemas/MediaType","description":"Media category: image, video, audio, or file"},"media_extension":{"$ref":"#/components/schemas/MediaExtension","description":"File extension: png, jpg, mp4, pdf, etc."},"visibility":{"$ref":"#/components/schemas/AssetVisibility","description":"Visibility level: private, public, or shared"},"bookmarked":{"type":"boolean","title":"Bookmarked","description":"Whether the asset is bookmarked","default":false},"archived":{"type":"boolean","title":"Archived","description":"Whether the asset is archived","default":false},"downloaded":{"type":"boolean","title":"Downloaded","description":"Whether the asset has been downloaded before","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the asset was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the asset was last modified"},"url":{"type":"string","title":"Url","description":"CDN URL for the asset (thumbnail/preview size)"},"large_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Large Url","description":"CDN URL for the full-resolution version"},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id","description":"ID of the agent that produced this asset. Null for uploaded assets."},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id","description":"ID of the run that produced this asset. Null for uploaded assets."},"asset_metadata":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"type":"object","title":"Asset Metadata","description":"Technical metadata: generation_model, aspect_ratio, duration, etc."},"is_flow_output_sample":{"type":"boolean","title":"Is Flow Output Sample","description":"Whether this asset is a sample output displayed on the agent card","default":false},"blur_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blur Hash","description":"BlurHash string for progressive image loading"}},"type":"object","required":["id","asset_type","media_type","media_extension","visibility","created_at","updated_at","url"],"title":"Asset","description":"Complete asset with all metadata."},"AssetType":{"type":"string","enum":["reference","intermediate","output"],"title":"AssetType","description":"Classification of assets by their role in workflows."},"MediaType":{"type":"string","enum":["image","video","audio","file"],"title":"MediaType","description":"Primary media categories for assets."},"MediaExtension":{"type":"string","enum":["png","jpg","jpeg","svg","heic","heif","avif","webp","mp4","wav","mp3","mov","webm","pdf","docx","csv","txt","json","md","ttf","otf","woff","woff2"],"title":"MediaExtension"},"AssetVisibility":{"type":"string","enum":["public","shared","private"],"title":"AssetVisibility"},"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"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/upload/":{"post":{"tags":["assets"],"summary":"Upload Asset","description":"Upload an asset file.\n\nThis endpoint handles the complete asset upload process in a single request.\nSimply send your file and get back a complete, ready-to-use asset.\n\n**Request (multipart/form-data):**\n- `file`: The file to upload (required)\n- `visibility`: Asset visibility level (default: \"private\")\n  - `\"private\"`: Only accessible by your organization\n  - `\"public\"`: Accessible by everyone\n  - `\"shared\"`: Accessible via shared links\n- `filename`: Optional custom display filename\n- `external_id`: Optional client-supplied reference id (≤255 chars), unique\n  per organization. Makes the upload safe to retry — reusing a key returns\n  `409` instead of a duplicate asset; fetch the existing one via\n  `GET /assets?external_id=`.\n\n**Supported File Types:**\nImages, videos, audio files, and documents (PNG, JPEG, MP4, PDF, etc.)\n\n**Response:**\nReturns a complete `Asset` object ready to use immediately (with `external_id`\nechoed).\n\n**Processing:**\nThe asset is automatically processed in the background after upload,\nincluding thumbnail generation and metadata extraction.\n\n**Errors:**\n- 400: Invalid or unsupported file type, or file cannot be read\n- 409: `external_id` already used by another asset (don't retry; GET it instead)\n- 413: File too large\n- 500: Server error during upload or processing\n- 503: Storage service temporarily unavailable","operationId":"upload_asset_assets_upload__post","parameters":[{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_asset_assets_upload__post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Download Asset

> Download the actual file content of an asset.\
> \
> This endpoint streams the binary file content of an asset. It's used to retrieve\
> generated assets from agent executions, download uploaded files, or access\
> assets for further processing.\
> \
> \*\*Primary Use Cases:\*\*\
> \- Download generated images/videos from completed agent executions\
> \- Retrieve uploaded assets for local processing or display\
> \
> \*\*Parameters:\*\*\
> \- \`asset\_id\`: Asset UUID identifier\
> \- \`svg\`: Optional boolean to convert images to SVG format (experimental feature)\
> \
> \*\*Access Control:\*\*\
> \- Same access rules as \`GET /{asset\_id}\` endpoint\
> \- Asset must be accessible to the authenticated user\
> \
> \*\*Errors:\*\*\
> \- 404: Asset not found or access denied\
> \- 410: Asset file no longer available (expired or deleted)

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"assets","description":"Upload, retrieve, and download files used as inputs or generated as outputs."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"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"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/download":{"get":{"tags":["assets"],"summary":"Download Asset","description":"Download the actual file content of an asset.\n\nThis endpoint streams the binary file content of an asset. It's used to retrieve\ngenerated assets from agent executions, download uploaded files, or access\nassets for further processing.\n\n**Primary Use Cases:**\n- Download generated images/videos from completed agent executions\n- Retrieve uploaded assets for local processing or display\n\n**Parameters:**\n- `asset_id`: Asset UUID identifier\n- `svg`: Optional boolean to convert images to SVG format (experimental feature)\n\n**Access Control:**\n- Same access rules as `GET /{asset_id}` endpoint\n- Asset must be accessible to the authenticated user\n\n**Errors:**\n- 404: Asset not found or access denied\n- 410: Asset file no longer available (expired or deleted)","operationId":"download_asset_assets__asset_id__download_get","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Asset Id"}},{"name":"svg","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Convert image to SVG format if applicable","title":"Svg"},"description":"Convert image to SVG format if applicable"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```