Assets

Assets are files you upload or that are generated through the API. They serve as inputs for agent executions (product photos, logos) and outputs produced by agents (images, videos). Use these endpoints to upload, retrieve metadata, and download files across the full asset lifecycle.

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

List Assets

get

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, ?asset_ids=<id>&agent_id=<agent> returns the asset only if it was produced by that agent; otherwise the response is empty.
agent_id and run_id only match assets that were produced by an agent 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 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

Authorizations

Query parameters

asset_idsstring · uuid[] · nullableOptional

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.

agent_idstring · uuid · nullableOptional

Return only assets produced by this agent (across all its runs). Uploaded assets are never returned by this filter.

run_idstring · uuid · nullableOptional

Return only assets produced by this specific run. Uploaded assets are never returned by this filter.

external_idstring · nullableOptional

Return the asset you uploaded with this reference id. Use after a 409 on upload to fetch the existing asset.

limitinteger · min: 1 · max: 100Optional

Maximum number of items to return

Default: 20

cursorstring · nullableOptional

Cursor for pagination (from next_cursor)

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

200

Successful Response

application/json

has_morebooleanRequired

next_cursorstring · nullableOptional

422

Validation Error

application/json

get/assets/

GET /api/public/v1/assets/ HTTP/1.1
Host: api.pletor.ai
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "external_id": "text",
      "asset_type": "reference",
      "media_type": "image",
      "media_extension": "png",
      "visibility": "public",
      "bookmarked": false,
      "archived": false,
      "downloaded": false,
      "created_at": "2026-07-17T02:34:05.045Z",
      "updated_at": "2026-07-17T02:34:05.045Z",
      "url": "text",
      "large_url": "text",
      "agent_id": "123e4567-e89b-12d3-a456-426614174000",
      "run_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "has_more": true,
  "next_cursor": "text"
}

Get Asset

get

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

Authorizations

Path parameters

asset_idstring · uuidRequired

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

200

Successful Response

application/json

Complete asset with all metadata.

idstring · uuidRequired

Unique asset identifier

external_idstring · nullableOptional

Client-supplied reference id provided at upload, if any

asset_typestring · enumRequired

Asset role: reference (input), intermediate, or output

Possible values:

media_typestring · enumRequired

Media category: image, video, audio, or file

Possible values:

media_extensionstring · enumRequired

File extension: png, jpg, mp4, pdf, etc.

Possible values:

visibilitystring · enumRequired

Visibility level: private, public, or shared

Possible values:

bookmarkedbooleanOptional

Whether the asset is bookmarked

Default: false

archivedbooleanOptional

Whether the asset is archived

Default: false

downloadedbooleanOptional

Whether the asset has been downloaded before

Default: false

created_atstring · date-timeRequired

When the asset was created

updated_atstring · date-timeRequired

When the asset was last modified

urlstringRequired

CDN URL for the asset (thumbnail/preview size)

large_urlstring · nullableOptional

CDN URL for the full-resolution version

agent_idstring · uuid · nullableOptional

ID of the agent that produced this asset. Null for uploaded assets.

run_idstring · uuid · nullableOptional

ID of the run that produced this asset. Null for uploaded assets.

is_flow_output_samplebooleanOptional

Whether this asset is a sample output displayed on the agent card

Default: false

blur_hashstring · nullableOptional

BlurHash string for progressive image loading

422

Validation Error

application/json

get/assets/{asset_id}

GET /api/public/v1/assets/{asset_id} HTTP/1.1
Host: api.pletor.ai
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "external_id": "text",
  "asset_type": "reference",
  "media_type": "image",
  "media_extension": "png",
  "visibility": "public",
  "bookmarked": false,
  "archived": false,
  "downloaded": false,
  "created_at": "2026-07-17T02:34:05.045Z",
  "updated_at": "2026-07-17T02:34:05.045Z",
  "url": "text",
  "large_url": "text",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "run_id": "123e4567-e89b-12d3-a456-426614174000",
  "asset_metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "is_flow_output_sample": false,
  "blur_hash": "text"
}

Delete Asset

delete

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 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

Authorizations

Path parameters

asset_idstring · uuidRequired

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

204

Successful Response

No content

422

Validation Error

application/json

delete/assets/{asset_id}

DELETE /api/public/v1/assets/{asset_id} HTTP/1.1
Host: api.pletor.ai
Accept: */*

No content

Upload Asset

post

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")
- "private": Only accessible by your organization
- "public": Accessible by everyone
- "shared": Accessible via shared links
filename: Optional custom display filename
external_id: Optional client-supplied reference id (≤255 chars), unique per organization. Makes the upload safe to retry — reusing a key returns 409 instead of a duplicate asset; fetch the existing one via 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

Authorizations

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Body

filestringRequired

visibilitystringOptional

Asset visibility level

Default: private

filenamestring · nullableOptional

Optional custom filename

external_idstring · max: 255 · nullableOptional

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.

Responses

200

Successful Response

application/json

Complete asset with all metadata.

idstring · uuidRequired

Unique asset identifier

external_idstring · nullableOptional

Client-supplied reference id provided at upload, if any

asset_typestring · enumRequired

Asset role: reference (input), intermediate, or output

Possible values:

media_typestring · enumRequired

Media category: image, video, audio, or file

Possible values:

media_extensionstring · enumRequired

File extension: png, jpg, mp4, pdf, etc.

Possible values:

visibilitystring · enumRequired

Visibility level: private, public, or shared

Possible values:

bookmarkedbooleanOptional

Whether the asset is bookmarked

Default: false

archivedbooleanOptional

Whether the asset is archived

Default: false

downloadedbooleanOptional

Whether the asset has been downloaded before

Default: false

created_atstring · date-timeRequired

When the asset was created

updated_atstring · date-timeRequired

When the asset was last modified

urlstringRequired

CDN URL for the asset (thumbnail/preview size)

large_urlstring · nullableOptional

CDN URL for the full-resolution version

agent_idstring · uuid · nullableOptional

ID of the agent that produced this asset. Null for uploaded assets.

run_idstring · uuid · nullableOptional

ID of the run that produced this asset. Null for uploaded assets.

is_flow_output_samplebooleanOptional

Whether this asset is a sample output displayed on the agent card

Default: false

blur_hashstring · nullableOptional

BlurHash string for progressive image loading

422

Validation Error

application/json

post/assets/upload/

POST /api/public/v1/assets/upload/ HTTP/1.1
Host: api.pletor.ai
Content-Type: multipart/form-data
Accept: */*
Content-Length: 77

{
  "file": "text",
  "visibility": "private",
  "filename": "text",
  "external_id": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "external_id": "text",
  "asset_type": "reference",
  "media_type": "image",
  "media_extension": "png",
  "visibility": "public",
  "bookmarked": false,
  "archived": false,
  "downloaded": false,
  "created_at": "2026-07-17T02:34:05.045Z",
  "updated_at": "2026-07-17T02:34:05.045Z",
  "url": "text",
  "large_url": "text",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "run_id": "123e4567-e89b-12d3-a456-426614174000",
  "asset_metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "is_flow_output_sample": false,
  "blur_hash": "text"
}

Download Asset

get

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)

Authorizations

Path parameters

asset_idstring · uuidRequired

Query parameters

svgboolean · nullableOptional

Convert image to SVG format if applicable

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/json

get/assets/{asset_id}/download

GET /api/public/v1/assets/{asset_id}/download HTTP/1.1
Host: api.pletor.ai
Accept: */*

No content

PreviousApp Runs NextModels

Last updated 20 days ago