API reference / Assets

Assets

Asset lifecycle, ingest, upload, transcode, package, thumbnails, tracks, tags, delivery.

GET /api/v1/assets/

List workspace assets.

Parameters

NameInTypeRequired
limitqueryintegeroptional
offsetqueryintegeroptional
statusquerystring (uploading, processing, ready, failed, archived)optional
parentIdquerystringoptional

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 notes
  • name — 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

NameInTypeRequired
tamsFlowIdquerystringrequired
tamsTimerangequerystringoptional

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 notes
  • name — 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/{id}

Get a single asset.

Parameters

NameInTypeRequired
idpathstringrequired

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 notes
  • name — 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

NameInTypeRequired
idpathstringrequired

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 notes
  • name — 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

NameInTypeRequired
idpathstringrequired

Response

Response 204 (application/json)
"null"

POST /api/v1/assets/{id}/audio-tracks

Add an audio track to an asset.

Parameters

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired
trackIdpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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 notes
  • name — 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}/comments

List review comments on an asset.

Parameters

NameInTypeRequired
idpathstringrequired

Response

Response 200 (application/json)
[
  {
    "id": "string",
    "assetId": "string",
    "body": "string",
    "createdAt": "string"
  }
]

POST /api/v1/assets/{id}/comments

Add a review comment to an asset.

Parameters

NameInTypeRequired
idpathstringrequired

Request

Request body (application/json)
{
  "body": "string"
}

Response

Response 201 (application/json)
{
  "id": "string",
  "assetId": "string",
  "body": "string",
  "createdAt": "string"
}

GET /api/v1/assets/{id}/delivery

Get playback URLs for an asset (HLS/DASH manifests and/or presigned source download).

Parameters

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired
execIdpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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 notes
  • name — 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}/extract-metadata

Extract technical metadata (codec, resolution, duration, bitrate) from the asset's source file.

Parameters

NameInTypeRequired
idpathstringrequired

Response

Response 200 (application/json)
{
  "assetId": "string",
  "status": "string"
}

GET /api/v1/assets/{id}/files

List the source and derived media files stored for an asset.

Parameters

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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 notes
  • name — 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

NameInTypeRequired
idpathstringrequired

Response

Response 200 (application/json)
{
  "uploadId": "string",
  "objectKey": "string",
  "expiresInSeconds": 0
}

DELETE /api/v1/assets/{id}/multipart/{uploadId}

Abort a multipart upload.

Parameters

NameInTypeRequired
idpathstringrequired
uploadIdpathstringrequired

Response

Response 204 (application/json)
"null"

POST /api/v1/assets/{id}/multipart/{uploadId}/complete

Complete a multipart upload.

Parameters

NameInTypeRequired
idpathstringrequired
uploadIdpathstringrequired

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

NameInTypeRequired
partNumberqueryintegerrequired
idpathstringrequired
uploadIdpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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 notes
  • name — 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

NameInTypeRequired
idpathstringrequired

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 notes
  • name — 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

NameInTypeRequired
idpathstringrequired
*pathstringrequired

Response

Response 200
(no body)

POST /api/v1/assets/{id}/subtitle-tracks

Add a subtitle track to an asset.

Parameters

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired
trackIdpathstringrequired

Response

Response 204 (application/json)
"null"

POST /api/v1/assets/{id}/tags

Add a tag to an asset.

Parameters

NameInTypeRequired
idpathstringrequired

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 notes
  • name — 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

NameInTypeRequired
idpathstringrequired
tagpathstringrequired

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 notes
  • name — 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

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired
indexpathstringrequired

Response

Response 200
(no body)

GET /api/v1/assets/{id}/tracks

List an asset's audio and subtitle tracks.

Parameters

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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 notes
  • warning — 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

NameInTypeRequired
idpathstringrequired

Response

Response 200 (application/json)
{
  "id": "string",
  "status": "string"
}

POST /api/v1/assets/{id}/upload-complete

Finalize a completed direct or presigned upload.

Parameters

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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

NameInTypeRequired
idpathstringrequired

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"
    }
  ]
}