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

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