Asset Management

Overview

The Asset Management API provides comprehensive endpoints for managing media assets including upload, retrieval, processing, organization, and lifecycle management. Assets can be files (video, audio, image, document) or folders for organizing content.

Base Routes

Asset Types

Asset Lifecycle

Creating Assets

Assets can be created in several ways:

1. Upload a file:
   POST /asset/upload/start           - Get pre-signed part URLs
   PUT  <part-url>                    - Upload each part directly
   POST /asset/upload/part/{id}/complete - Confirm each part
   POST /asset/upload/{id}/complete   - Finalize upload and trigger processing

2. Register an existing storage object:
   POST /admin/asset/register         - Register by bucket name + object key

3. Create organizational structure:
   POST /admin/asset/{parentId}/create-folder      - Create a folder
   POST /admin/asset/{parentId}/create-placeholder  - Create a placeholder

Asset Statuses

Assets transition through statuses during their lifecycle:

Multipart Upload Flow

Large files are uploaded using a multipart process:

1. POST /asset/upload/start
   Request: { fileName, fileSize, parentId, contentType, ... }
   Response: { id, parts: [{ partNumber, uploadUrl, ... }] }

2. For each part:
   PUT <uploadUrl> with file chunk data
   Response includes ETag header

3. POST /asset/upload/part/{partId}/complete
   Request: { etag: "<from-step-2>" }

4. POST /asset/upload/{uploadId}/complete
   Triggers post-upload processing (transcoding, AI, indexing)

To cancel an in-progress upload:

POST /asset/upload/{uploadId}/cancel
Cleans up all partial data

Related Asset Uploads

To upload supplementary files (subtitles, proxies, thumbnails):

POST /asset/upload/start-related-asset
Same flow as above, but includes parentAssetId and relationship type

Asset Retrieval

Folder Operations

Creating Folders

POST /admin/asset/{parentId}/create-folder
Request body: { displayName: "Folder Name" }
Response: { id, displayName, ... }

create-folder is synchronous — the response includes the new folder's id immediately. You can use the returned ID to create child folders without any polling or delay.

Folder URL format: All folder URLs in the system end with a trailing /. Include the trailing slash when constructing or comparing folder URL strings:

✓  Content/Photo/Events/2024/
✗  Content/Photo/Events/2024

Creating large folder trees: When creating a hierarchy of folders, process them top-down sorted by path depth so each parent exists before its children are created. Adding a brief pause between depth levels (≈1 second) gives the system time to register each parent before children are appended. Creating children before their parents results in errors.

Moving and Renaming Assets

POST /admin/asset/{id}/move
Request body: { parentId, displayName }

• Provide a new parentId to move the asset to a different folder.
• Provide a new displayName (same parentId) to rename in place without a physical file move.
• Provide both to move and rename simultaneously.

Deleting Folders — Cascade Behavior

⚠️

Deleting a folder permanently deletes all of its descendants. There is no confirmation or recovery step. Subfolders and all files within them are removed.

DELETE /admin/asset/{id}

Before deleting any folder, verify that neither it nor any folder beneath it is a destination you intend to keep. A safe deletion guard:

1. Collect all URLs of folders you need to keep (e.g. your plan's destination folder list).
2. For each candidate folder to delete, check that its URL is not an exact match or a URL prefix of any protected folder.
3. Only delete candidates that pass both checks.

Deleting at too high a level in the tree silently removes everything beneath — including folders created moments before in the same operation.

Resolving the Ancestor Hierarchy

GET /admin/asset/{id}/parent-folders
Response: { items: [{ id, identifiers: { children: { items: [...] } } }] }

Returns the full ancestor chain from the root down to the asset's direct parent. The response is a nested structure — children are under identifiers.children.items, not identifiers.children directly. Walk the chain to reach the deepest node (the immediate parent):

function deepestFolder(result) {
  let current = result?.items?.[0];
  while (current?.identifiers?.children?.items?.length > 0) {
    current = current.identifiers.children.items[0];
  }
  return current; // direct parent folder
}

System Hierarchy vs. Storage URL

The system's parent-folder hierarchy (what parent-folders traverses) may differ from the S3/CDN URL path shown on the asset. An asset at Content/Photo/Canto Download/2024/Event/ in its storage URL may physically sit under Content/Contractors/ in the system hierarchy due to legacy migrations or import configuration.

Use parentId-based search to navigate the system tree reliably:

// ✓ Navigate by system hierarchy
{ fieldName: "parentId", operator: "Equals", values: "<known-folder-id>" }

// ⚠ url-Equals matches by storage URL prefix — may not reflect system hierarchy
{ fieldName: "url", operator: "Equals", values: "Content/Photo/Canto Download/2024/" }

Asset Operations

Updating Properties

PATCH /admin/asset/{id}  (or PATCH /asset/{id})
Request: { displayName, description, ... }
Updates lightweight properties without triggering reprocessing

Changing Language

POST /admin/asset/{id}/language
Request: { languageCode }
Triggers AI reprocessing (transcription, subtitles) for the new language

Clipping Video

POST /admin/asset/{id}/clip  (or POST /asset/{id}/clip)
Request: { startTimecode, endTimecode, ... }
Creates a new clip asset from the specified timecode range

Capturing Screenshots

POST /admin/asset/{id}/screenshot
Request: { timecodeMilliseconds }
Generates a still image at the specified timecode

Sharing Assets

POST /asset/{assetId}/share
Request: { recipients, expirationDate, password, ... }
Returns a shareable URL

Batch Operations

Execute operations on multiple assets at once:

POST /admin/asset/{actionName}
Request: { targetIds: [...], actionArguments: { ... } }
Returns batch result with per-asset status

Common batch action names (case-insensitive):

Archive & Restore

Archiving

POST /admin/asset/{id}/archive
Requires file write permission
Moves asset to cost-effective archival storage
Asset becomes unavailable for streaming/download until restored

Restoring

POST /admin/asset/{id}/restore  (or POST /asset/{id}/restore)
Requires file write permission (admin only)
Restoration time depends on archive storage tier
Monitor progress via job history

Local Restore (On-Premises)

POST /asset/local-restore
Request: { sourceAssetIds: [...], restoreProfileNames: [...] }
Restores to on-premises storage using configured profiles

POST /asset/{id}/localRestore
Same as above, for a single asset

Annotations

Annotations allow marking up assets with notes, markers, and comments.

Transcription & Subtitles

Updating Transcription

POST /asset/{assetId}/transcript/{transcriptId}
Request: [{ text, startTime, endTime, ... }]
Updates word-level transcription data

Getting Transcription Words

GET /admin/asset/{id}/transcription-words
Returns word-level transcription with timings and confidence scores

Exporting Subtitles

POST /asset/{id}/subtitle/{relatedAssetId}/export
Request: { exportFormat: "SRT" | "VTT" | "DocX" | "Text" }
Returns the subtitle file as a binary download

Ad Breaks (VMAP/VAST)

Managing Ad Breaks

Ad Serving (Public Endpoints)

Metadata & Labels

GET /admin/asset/{id}/metadata-summary
Returns AI-detected labels and metadata for an asset or folder
For folders, aggregates labels across all child assets

Job History

GET /admin/asset/{assetId}/job-history
Returns chronological processing job history
Includes: job type, status, start/end times, error details

Download Queue

Collect assets for batch download:

Add to Queue

Endpoint: POST /asset-queue

Description: Adds assets to the user's download queue. Supports individual file assets, folders, and collections. Folders and collections are automatically expanded to include all file assets they contain.

Request Body:

{
  "ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "7ba85f64-5717-4562-b3fc-2c963f66afa7",
    "9ca85f64-5717-4562-b3fc-2c963f66afa8"
  ],
  "downloadProxy": false
}

Behavior:

• Automatic Expansion: Folder and collection IDs are automatically expanded to include all file assets within them
• File Assets Only: Only file assets (assetType = 2) are added to the queue; folder/collection IDs themselves are never queued
• Threshold Logic:
  • ≤50 asset IDs in request: Processed synchronously, response returned after completion

  • 50 asset IDs in request: Queued as background task, response returned immediately

• User Security: Only assets the user has access to are included
• Duplicate Handling: Assets already in the queue with status "Queued" or "Downloading" are skipped

Error Responses:

• 400 Bad Request - No asset IDs provided
• 401 Unauthorized - Caller is not authenticated

Creating ZIP Archives

POST /admin/asset/download-archive  (or POST /asset/download-archive)
Request: { assetIds: [...], filename, downloadProxy }
Creates a ZIP archive of multiple assets for download

Secure Streaming

GET /admin/asset/{assetId}/set-cookies/{relatedAssetId}
GET /asset/{assetId}/set-cookies/{relatedAssetId}
Returns signed streaming cookies for secure media playback
Cookies are set in both response headers and body

Video Tracking

GET /asset/tracking?trackingEvent=...&assetId=...&second=...
Records playback events (play, pause, quartile, complete)
Used as a tracking beacon/pixel endpoint
Supports both asset and live channel tracking

Facial Recognition

Person-Face Association

POST /asset/{assetId}/assign-person/{faceId}/{personId}
Associates a detected face with a known person record

POST /asset/{assetId}/remove-person/{faceId}
Removes the person association from a detected face

AI Image Generation

POST /asset/{assetId}/generate-image
Request: { prompt: "description of image to generate", ... }
Creates a new image asset using AI generation

URL Resolution

GET /admin/asset/{assetId}/resolve-full-url?url=...
Converts a relative asset URL to a fully signed, accessible URL

Common Error Responses