Assets
Asset lifecycle, ingest, upload, transcode, package, thumbnails, tracks, tags, delivery.
GET /api/v1/assets/
List workspace assets.
Parameters
| Name | In | Type | Required |
|---|
limit | query | integer | optional |
offset | query | integer | optional |
status | query | string (uploading, processing, ready, failed, archived) | optional |
parentId | query | string | optional |
Response
Response 200 (application/json)
{
"items": [
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": null,
"from": null,
"to": null
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
],
"limit": 0,
"offset": 0,
"total": 0
}
POST /api/v1/assets/
Create an asset record.
Request
Request body (application/json)
{
"name": "string",
"slug": "string",
"description": "string",
"parentId": "string",
"objectKey": "string",
"metadata": {},
"tags": [
"string"
]
}
Response
Response 201 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
GET /api/v1/assets/by-tams-address
Look up an asset by its TAMS flow/timerange address.
Parameters
| Name | In | Type | Required |
|---|
tamsFlowId | query | string | required |
tamsTimerange | query | string | optional |
Response
Response 200 (application/json)
{
"items": [
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": null,
"from": null,
"to": null
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
],
"limit": 0,
"offset": 0,
"total": 0
}
POST /api/v1/assets/ingest-url
Ingest a video from a public URL into a new asset.
Request
Request body (application/json)
{
"sourceUrl": "string",
"name": "string",
"description": "string",
"title": "string",
"tags": [
"string"
]
}
Field notesname — Legacy alias for `title` (issue #347). The editorial title of the asset. `title` and `name` are two input spellings of the SAME canonical field: both persist to `descriptive.title` and are read back as the `name` property on GET /assets/:id, list, and search responses. Prefer `title`; `title` wins when both are supplied.title — The editorial title of the asset (issue #347). This is the canonical write path for title: it persists to `descriptive.title` and is read back as the `name` property on GET /assets/:id, list, and search responses (there is NO separate top-level `title` field on responses). Accepted as an alias of `name`; `title` wins when both are supplied.
Response
Response 202 (application/json)
{
"assetId": "string",
"jobId": "string"
}
GET /api/v1/assets/search
Deprecated legacy free-text-only search alias. Use the canonical Search endpoint instead.
Parameters
| Name | In | Type | Required |
|---|
q | query | string | required |
Response
Response 200 (application/json)
{
"items": [
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": null,
"from": null,
"to": null
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
]
}
GET /api/v1/assets/{id}
Get a single asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
PATCH /api/v1/assets/{id}
Update asset fields.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"name": "string",
"description": "string",
"objectKey": "string",
"status": "uploading",
"metadata": {},
"tags": [
"string"
]
}
Response
Response 200 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
DELETE /api/v1/assets/{id}
Delete an asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 204 (application/json)
"null"
POST /api/v1/assets/{id}/audio-tracks
Add an audio track to an asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"language": "string",
"codec": "string",
"channels": 0,
"label": "string",
"default": true
}
Response
Response 201 (application/json)
{
"audioTracks": [
{
"id": "string",
"language": "string",
"codec": "string",
"channels": 0,
"label": "string",
"default": true
}
]
}
DELETE /api/v1/assets/{id}/audio-tracks/{trackId}
Remove an audio track.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
trackId | path | string | required |
Response
Response 204 (application/json)
"null"
POST /api/v1/assets/{id}/clip
Clip a time segment of the asset into a new child asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"startSeconds": 0,
"endSeconds": 0,
"outputName": "string",
"asVersion": true
}
Response
Response 201 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
GET /api/v1/assets/{id}/delivery
Get playback URLs for an asset (HLS/DASH manifests and/or presigned source download).
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"assetId": "string",
"status": "ready",
"urls": {
"hls": "string",
"dash": "string",
"source": "string"
},
"expiresAt": "string",
"resolution": {
"packagedBucket": "string",
"packagedPrefix": "string",
"masterHlsKey": "string",
"masterDashKey": "string"
}
}
POST /api/v1/assets/{id}/execute
Run a multi-step pipeline execution (e.g. transcode + package) against the asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"pipeline": "transcode",
"profile": "string",
"customProfile": {
"name": "string",
"outputs": [
{
"label": "string",
"width": 0,
"height": 0,
"videoBitrateBps": 0,
"audioBitrateBps": 0,
"format": "string"
}
]
},
"profileParams": {},
"destinationBucket": "string"
}
Response
Response 202 (application/json)
{
"id": "string",
"assetId": "string",
"pipelineName": "string",
"status": "running",
"steps": [
{
"name": "extract-metadata",
"status": "pending",
"jobId": "string",
"encoreJobId": "string",
"error": "string",
"startedAt": "string",
"completedAt": "string",
"progress": 0
}
],
"createdAt": "string",
"updatedAt": "string",
"destinationBucket": "string"
}
GET /api/v1/assets/{id}/executions
List pipeline executions for an asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
[
{
"id": "string",
"assetId": "string",
"pipelineName": "string",
"status": "running",
"steps": [
{
"name": "extract-metadata",
"status": "pending",
"jobId": "string",
"encoreJobId": "string",
"error": "string",
"startedAt": "string",
"completedAt": "string",
"progress": 0
}
],
"createdAt": "string",
"updatedAt": "string",
"destinationBucket": "string"
}
]
GET /api/v1/assets/{id}/executions/{execId}
Get a single pipeline execution.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
execId | path | string | required |
Response
Response 200 (application/json)
{
"id": "string",
"assetId": "string",
"pipelineName": "string",
"status": "running",
"steps": [
{
"name": "extract-metadata",
"status": "pending",
"jobId": "string",
"encoreJobId": "string",
"error": "string",
"startedAt": "string",
"completedAt": "string",
"progress": 0
}
],
"createdAt": "string",
"updatedAt": "string",
"destinationBucket": "string"
}
POST /api/v1/assets/{id}/export
Re-wrap the asset into a different container format without re-encoding.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"targetFormat": "mp4",
"outputName": "string",
"asVersion": true
}
Response
Response 201 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
GET /api/v1/assets/{id}/files
List the source and derived media files stored for an asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"files": [
{
"id": "string",
"type": "source",
"name": "string",
"format": "string",
"objectKey": "string",
"url": "string",
"sizeBytes": 0,
"label": "string",
"width": 0,
"height": 0,
"bitrateBps": 0,
"codec": "string"
}
],
"fileGroups": [
{
"id": "string",
"type": "hls-package",
"name": "string",
"manifestUrl": "string",
"objectKeyPrefix": "string",
"segmentCount": 0
}
]
}
PUT /api/v1/assets/{id}/metadata
Replace an asset's free-form metadata.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{}
Response
Response 200 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
POST /api/v1/assets/{id}/multipart/initiate
Initiate a multipart upload for large source media.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"uploadId": "string",
"objectKey": "string",
"expiresInSeconds": 0
}
DELETE /api/v1/assets/{id}/multipart/{uploadId}
Abort a multipart upload.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
uploadId | path | string | required |
Response
Response 204 (application/json)
"null"
POST /api/v1/assets/{id}/multipart/{uploadId}/complete
Complete a multipart upload.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
uploadId | path | string | required |
Request
Request body (application/json)
{
"parts": [
{
"partNumber": 0,
"etag": "string"
}
]
}
Response
Response 200 (application/json)
{
"id": "string",
"status": "string"
}
GET /api/v1/assets/{id}/multipart/{uploadId}/part-url
Get a presigned URL for one multipart upload part.
Parameters
| Name | In | Type | Required |
|---|
partNumber | query | integer | required |
id | path | string | required |
uploadId | path | string | required |
Response
Response 200 (application/json)
{
"url": "string",
"partNumber": 0,
"expiresInSeconds": 0
}
POST /api/v1/assets/{id}/package
Submit an HLS/DASH packaging job for the asset's transcoded renditions.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"encoreJobId": "string"
}
Response
Response 202 (application/json)
{
"ok": true,
"jobId": "string",
"pipelineMode": true
}
GET /api/v1/assets/{id}/pipelines
List pipeline definitions available to run against the asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
[
{
"id": "string",
"assetId": "string",
"pipelineName": "string",
"status": "running",
"steps": [
{
"name": "extract-metadata",
"status": "pending",
"jobId": "string",
"encoreJobId": "string",
"error": "string",
"startedAt": "string",
"completedAt": "string",
"progress": 0
}
],
"createdAt": "string",
"updatedAt": "string",
"destinationBucket": "string"
}
]
POST /api/v1/assets/{id}/restore
Restore a soft-deleted asset within its retention window.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
POST /api/v1/assets/{id}/review-state
Transition an asset's editorial review state (draft / in-review / approved / rejected).
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"reviewState": "draft"
}
Response
Response 200 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
GET /api/v1/assets/{id}/stream/{*}
Proxy-stream a packaged HLS/DASH manifest or media segment.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
* | path | string | required |
Response
POST /api/v1/assets/{id}/subtitle-tracks
Add a subtitle track to an asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"language": "string",
"format": "vtt",
"label": "string",
"default": true
}
Response
Response 201 (application/json)
{
"track": {
"id": "string",
"language": "string",
"format": "vtt",
"objectKey": "string",
"label": "string",
"default": true
},
"uploadUrl": "string"
}
DELETE /api/v1/assets/{id}/subtitle-tracks/{trackId}
Remove a subtitle track.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
trackId | path | string | required |
Response
Response 204 (application/json)
"null"
POST /api/v1/assets/{id}/tags
Add a tag to an asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"tags": [
"string"
]
}
Response
Response 200 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
DELETE /api/v1/assets/{id}/tags/{tag}
Remove a tag from an asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
tag | path | string | required |
Response
Response 200 (application/json)
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": "string",
"from": "uploading",
"to": "uploading"
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
Field notesname — Canonical editorial title of the asset. Set on ingest via `title` (or the legacy `name` alias) and persisted to `descriptive.title`; this is the single documented location for title across GET, list, and search responses. There is no separate top-level `title` field.
GET /api/v1/assets/{id}/thumbnails
List extracted thumbnails.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"assetId": "string",
"thumbnails": [
"string"
]
}
POST /api/v1/assets/{id}/thumbnails
Extract poster frame thumbnails at one or more timecodes.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"timecodes": [
0
]
}
Response
Response 200 (application/json)
{
"assetId": "string",
"thumbnails": [
"string"
]
}
GET /api/v1/assets/{id}/thumbnails/{index}
Get a single extracted thumbnail.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
index | path | string | required |
Response
GET /api/v1/assets/{id}/tracks
List an asset's audio and subtitle tracks.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"audioTracks": [
{
"id": "string",
"language": "string",
"codec": "string",
"channels": 0,
"label": "string",
"default": true
}
],
"subtitleTracks": [
{
"id": "string",
"language": "string",
"format": "vtt",
"objectKey": "string",
"label": "string",
"default": true
}
]
}
POST /api/v1/assets/{id}/transcode
Submit an ABR transcoding job for the asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Request
Request body (application/json)
{
"profile": "string",
"customProfile": {
"name": "string",
"outputs": [
{
"label": "string",
"width": 0,
"height": 0,
"videoBitrateBps": 0,
"audioBitrateBps": 0,
"format": "string"
}
]
},
"profileParams": {},
"burnIn": {
"source": null,
"forceStyle": "string"
}
}
Response
Response 202 (application/json)
{
"jobId": "string",
"encoreJobId": "string",
"warning": {
"code": "profile_params_unvalidated",
"message": "string",
"profile": "string",
"unvalidatedKeys": [
"string"
]
}
}
Field noteswarning — Present only when profileParams validation could not be performed because the profile YAML was unresolvable (a custom profile not in the store, or the profile store was unreachable). The request was still accepted and the keys were forwarded to Encore unchecked.
PUT /api/v1/assets/{id}/upload
Direct upload of source media for an asset.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"id": "string",
"status": "string"
}
POST /api/v1/assets/{id}/upload-complete
Finalize a completed direct or presigned upload.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"id": "string",
"status": "string"
}
POST /api/v1/assets/{id}/upload-url
Get a presigned single-part upload URL for an asset's source media.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"url": "string",
"objectKey": "string",
"method": "string",
"expiresInSeconds": 0
}
GET /api/v1/assets/{id}/versions
List an asset's version history.
Parameters
| Name | In | Type | Required |
|---|
id | path | string | required |
Response
Response 200 (application/json)
{
"assetId": "string",
"versions": [
{
"id": "string",
"name": "string",
"status": "uploading",
"statusHistory": [
{
"at": null,
"from": null,
"to": null
}
],
"createdAt": "string",
"updatedAt": "string",
"slug": "string",
"description": "string",
"reviewState": "draft",
"parentId": "string",
"versionOfAssetId": "string",
"versionGroupId": "string"
}
]
}