Assets

An asset is the core media record in the Media API. It points to content in a registered storage location and becomes the unit you pass into jobs, attach to streaming locators, inspect for tracks, and organize with labels. An asset maps to a container in Azure or a bucket in AWS storage. See Assets for the product background.

In a typical workflow you create an asset that points to source content or a target output location, run a job against it or write live output into it, then publish it through a streaming locator.

Create an asset

An asset is created with PUT. The only required field is properties.storageAccountName, which names the storage instance you registered. The rest position the asset within that storage and attach metadata.

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/source-video" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "storageAccountName": "primary-azure",
      "container": "source-video",
      "description": "Source video for encoding",
      "subPath": "incoming",
      "containerDeletionPolicy": "Retain"
    },
    "labels": {
      "series": "my-show",
      "season": "2"
    }
  }'

The fields worth knowing:

• storageAccountName (required): the registered storage instance to use.
• container: the storage container or bucket for the asset.
• subPath: a directory path inside the container. It is immutable after creation.
• containerDeletionPolicy: Delete or Retain. It controls whether deleting the asset also deletes the underlying storage container.
• labels: up to 32 key-value pairs, used for filtering and grouping.

Storage placement is fixed at creation. Treat storageAccountName, container, and subPath as create-time decisions in your automation.

Read the asset or just its state

Read the full asset with a GET:

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/source-video" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

When you only need readiness in a polling loop, read the lightweight state endpoint instead of the full object. See Resource states for the asset state values.

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/source-video/state" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Inspect tracks and request file access

Two read operations are commonly useful once an asset exists.

Enumerate the container contents and track listings, including language and bitrate where available:

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/source-video/storage/" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Request the information needed to read files directly from the underlying storage:

curl -X POST "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/source-video/getFileAccessInfo" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

The response returns storageAccountName, containerName, jwt, url, and an optional subPath. The storage instance must have a valid credential for this to succeed. For the full two-step download flow, see Download asset files.

Organize assets with labels

Labels are part of the asset schema and are designed for retrieval, not just description. Query by an exact label value:

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets?\$label=series=my-show" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Or require the presence of several keys at once:

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets?\$label_key=series&\$label_key=region" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

The asset list also supports $top, $skiptoken, $orderby, and $filter. See Pagination and filtering.

See where an asset is published

To find out whether an asset is already exposed for playback, list the locators attached to it rather than scanning every locator in the project:

curl -X POST "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/source-video/listStreamingLocators" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

What goes wrong

• Deleting an asset can delete the content. When containerDeletionPolicy is Delete, removing the asset also removes the underlying container and everything in it. Set Retain when the stored files must survive the asset record.
• getFileAccessInfo fails after a credential expires. The most common cause is an expired storage credential. Rotate it first; see Storage.
• Trying to move an asset after creation. Storage placement fields are immutable. To relocate content, create a new asset.

curl -X DELETE "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/source-video" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

What comes next

• Transforms and jobs: process assets through reusable transforms.
• Playback filters: publish a shaped subset of an asset.
• Streaming and publishing: publish assets for playback.