# List Transforms

> Media API · Transforms

```http
GET https://app.mk.io/api/v1/projects/{project_name}/media/transforms
```

## Listing, Sorting and Filtering Transforms

This endpoint returns the list of transforms in the specified project.

### Sorting

The results from this endpoint can be ordered using the `$orderby` query parameter. Specify a list of field names, separated by commas
where each one can optionally specify `asc` or `desc`.

Sorting is valid on the following fields: `created`, `createdBy`, `id`, `name`, `properties/created`, `properties/lastModified`, `updated`, `updatedBy`

### Filtering

The `$filter` query parameter allows for transforms to be filtered on the basis of fields in the schema using OData query syntax.
See [this document](https://learn.microsoft.com/en-us/odata/concepts/queryoptions-overview#filter) for more details on the syntax used.

Filters are valid on the following fields: `created`, `createdBy`, `createdByEmail`, `createdByName`, `id`, `name`, `properties/created`, `properties/lastModified`, `updated`, `updatedBy`, `updatedByEmail`, `updatedByName`

### Examples:

`?$top=10` - Returns only the first 10 transforms from the list.

`?$orderby=name desc` - Sorts transforms by name in descending order.

`?$filter=name eq 'descriptive name'` - Returns transforms that match the provided name.

`?$orderby=created desc` - Sorts transforms by creation date in descending order.

`?$filter=created ge 2021-01-01T00:00:00Z` - Returns transforms created after January 1, 2021.

RBAC Capability Required: `ams.transform.get`

## Authentication

- `Authorization` header — Bearer authentication of the form `Bearer <token>`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `project_name` | string | Yes | — |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `$orderby` | string | No | Specifies the key by which the result collection should be ordered. |
| `$filter` | string | No | Restricts the set of items returned. |
| `$top` | string | No | Specifies a non-negative integer `n` that limits the number of items returned from a collection. The service returns the number of available items up to but not greater than the specified value `n`. |
| `$skiptoken` | string | No | Specifies a start offset to support paginated results. Use `@odata.nextLink` in the result object to enumerate the collection - it will be present only if there's more than one page of entities. |

## Example request

```bash
curl -X GET "https://app.mk.io/api/v1/projects/{project_name}/media/transforms" \
  -H "Authorization: Bearer <token>"
```

## Responses

### 200 — A list of transforms

- `@odata.nextLink` · string · Optional — @odata.nextLink URL if the page length and number of items match.
- `supplemental` · object · **Required** — Supplemental info
  - `count` · integer · **Required** — Number of items returned
  - `kind` · string · **Required** — Type of items in the list
  - `operation` · string · **Required** — Operation type. Should always say 'list'
  - `pagination` · object · **Required** — Pagination info
    - `end` · integer · **Required** — Position of the last item in the list
    - `records` · integer · **Required** — Total number of items returned in the list
    - `start` · integer · **Required** — Position of the first item in the list
    - `total` · integer · **Required** — Total number of items in the project
  - `subscription` · object · Optional — Project info
    - `id` · string · **Required** — Project ID
    - `name` · string · **Required** — Project name
- `value` · list of objects · **Required** — A list of Transforms
  - Array items (object):
    - `id` · string · Optional — Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
    - `name` · string · Optional · _1-260 characters_ · _pattern: ^[^\^\'<>%&:\\?/*+]+$_ — The name of the resource
    - `properties` · object · **Required** — The properties of the Transform
      - `created` · string · Optional · _format: date-time_ — The creation date and time of the Transform. Set by the system.
      - `description` · string · Optional · _<=1024 characters_ — The description of the Transform.
      - `lastModified` · string · Optional · _format: date-time_ — The last modified date and time of the Transform. Set by the system.
      - `outputs` · list of objects · **Required** — An array of TransformOutputs that the Transform should generate. Currently limited to one.
        - Array items (object):
          - `onError` · enum · Optional — Defines what the service should do when one output fails. Continue to produce other outputs, or stop processing.
            - Allowed values: `ContinueJob`, `StopProcessingJob`
          - `preset` · object · **Required** — Preset that describes the operations that will be used to modify, transcode, or extract insights from the source file to generate the output.
            - One of the following variants, selected by `@odata.type`:
              - **#Microsoft.Media.BuiltInStandardEncoderPreset** (object)
                - `@odata.type` · string · **Required** — The discriminator for derived types.
                - `advancedSettingsName` · string · Optional — Name of the advanced settings configuration to apply to this transform's config. These configuration blocks are managed by MediaKind and you should not set this field unless MediaKind support has asked you to.
                - `presetName` · string · **Required** — The built-in preset to be used for encoding videos. Options include: * H264SingleBitrateSD * H264SingleBitrate720p * H264SingleBitrate1080p * H264MultipleBitrateSD * H264MultipleBitrate720p * H264MultipleBitrate1080p * H264MultipleBitrateSDWithCVQ * H264MultipleBitrate720pWithCVQ * H264MultipleBitrate1080pWithCVQ * H265SingleBitrate720p * H265SingleBitrate1080p * H265SingleBitrate4K * AACGoodQualityAudio
              - **#MediaKind.BuiltInAssetConverterPreset** (object)
                - `@odata.type` · string · **Required** — The discriminator for derived types.
                - `presetName` · enum · **Required** — The built-in preset to be used for performing asset conversion.
                  - Allowed values: `CopyTopBitrateInterleaved`, `CopyAllBitrateNonInterleaved`, `CopyAllBitrateInterleaved`
              - **#Microsoft.Media.BuiltInAssetConverterPreset** (object)
                - `@odata.type` · string · **Required** — The discriminator for derived types.
                - `presetName` · enum · **Required** — The built-in preset to be used for performing asset conversion.
                  - Allowed values: `CopyTopBitrateInterleaved`, `CopyAllBitrateNonInterleaved`, `CopyAllBitrateInterleaved`
              - **#MediaKind.ThumbnailGeneratorPreset** (object)
                - `@odata.type` · string · **Required** — The discriminator for derived types.
                - `baseFilename` · string · Optional · _<=64 characters_ · _pattern: ^[A-Za-z0-9_-]+$_ — Used to create the output filename as `{BaseFilename}_{Label}{Index}{Extension}`. The default is the name of the input file. If the name of the input file is too long then it will be truncated to 64 characters.
                - `thumbnails` · list of objects · **Required** · _1+ items_ — The set of thumbnails to be produced.
                  - Array items (object):
                    - `format` · enum · **Required** — The output format for the thumbnails.
                      - Allowed values: `Jpeg`, `Png`
                    - `height` · string · Optional — Either an integer size in pixels, or a percentage of the input resolution. If either width/height is defined as percentage, the other dimension must be the same percentage.
                    - `label` · string · Optional · _<=64 characters_ · _pattern: ^[A-Za-z0-9_-]+$_ — Used to create the output filename as `{BaseFilename}_{Label}{Index}{Extension}`. When generating sprites, the output vtt file will be named `{BaseFilename}_{Label}.vtt`
                    - `quality` · integer · Optional · _0 to 100_ · _Defaults to 70_ — The compression quality for JPEG images. Between 0-100, default: 70.
                    - `range` · string · Optional · _Defaults to 1_ — Either an ISO8601 duration, or a percentage of the asset duration, or the value '1'. The default is '1', a single thumbnail is produced.
                    - `spriteColumn` · integer · Optional · _1 to 10_ — The number of columns used if you want a thumbnail sprite image. Default: Single image output files.
                    - `start` · string · Optional · _Defaults to PT10S_ — Either an ISO8601 duration, or a percentage of the asset duration. Default: PT10S.
                    - `step` · string · Optional — The intervals at which thumbnails are generated. Either an ISO8601 duration, or a percentage of the asset duration.
                    - `width` · string · Optional — Either an integer size in pixels, or a percentage of the input resolution. If only one of width/height is present, the aspect ratio from the source is preserved.
              - **#MediaKind.TrackInserterPreset** (object)
                - `@odata.type` · string · **Required** — The discriminator for derived types.
                - `baseFilename` · string · Optional · _<=64 characters_ · _pattern: ^[A-Za-z0-9_-]+$_ — Used to create the output filename. - For text tracks: `{BaseFilename}.cmft`, the default being the input .vtt filename minus the extension, e.g. `subtitles.vtt` -> `subtitles.cmft`. - For audio tracks: `{BaseFilename}.mp4`, the default being the input .mp4 filename, ignored if the audio file is already present in the output asset.
                - `tracks` · list of objects · **Required** · _1-1 items_ — The set of tracks to be inserted. Currently limited to one.
                  - Array items (object):
                    - One of the following variants, selected by `@odata.type`:
                      - **#MediaKind.TextTrack** (object)
                        - `@odata.type` · string · **Required** — The discriminator for derived types.
                        - `displayName` · string · Optional — The display name of the track on a video player. In HLS, this maps to the NAME attribute of EXT-X-MEDIA.
                        - `hlsSettings` · object · Optional — The HLS specific setting for the track.
                          - `characteristics` · string · Optional — The characteristics for the HLS setting.
                          - `default` · boolean · Optional · _Defaults to false_ — Default track?
                          - `forced` · boolean · Optional · _Defaults to false_ — Forced track?
                        - `languageCode` · string · Optional — The RFC5646 language code for the track.
                        - `playerVisibility` · enum · Optional · _Defaults to Visible_ — When PlayerVisibility is set to 'Visible', the track will be present in the DASH manifest or HLS playlist when requested by a client. When the PlayerVisibility is set to 'Hidden', the track will not be available to the client. The default value is 'Visible'.
                          - Allowed values: `Visible`, `Hidden`
                        - `trackName` · string · **Required** — The name of the track in the manifest.
                      - **#MediaKind.AudioTrack** (object)
                        - `@odata.type` · string · **Required** — The discriminator for derived types.
                        - `dashSettings` · object · Optional — The DASH specific setting for the audio track.
                          - `role` · string · Optional — The role for the DASH setting.
                        - `displayName` · string · Optional — The display name of the audio track on a video player. In HLS, this maps to the NAME attribute of EXT-X-MEDIA.
                        - `hlsSettings` · object · Optional — The HLS specific setting for the audio track.
                          - `characteristics` · string · Optional — The characteristics for the HLS setting.
                          - `default` · boolean · Optional · _Defaults to false_ — Default track?
                          - `forced` · boolean · Optional · _Defaults to false_ — Forced track?
                        - `languageCode` · string · Optional — The RFC5646 language code for the audio track.
                        - `trackName` · string · **Required** — The name of the audio track in the manifest.
              - **#MediaKind.AIPipelinePreset** (object)
                - `@odata.type` · string · **Required** — The discriminator for derived types.
                - `pipeline` · object · **Required** — AI pipeline settings
                  - `arguments` · map from strings to list of objects · Optional — Arguments to each operation in the AI pipeline
                    - `[any key]` · list of objects — map of additional properties
                      - Array items (object):
                        - `name` · string · **Required** · _1-260 characters_ · _pattern: ^[A-Za-z0-9_-]+$_ — The name of the argument
                        - `value` · any · **Required** — The value of the argument
                  - `name` · string · **Required** · _0-255 characters_ — The name of the AI pipeline the Transform will execute.
              - **#MediaKind.EncoderPreset** (object)
                - `@odata.type` · string · **Required** — The discriminator for derived types.
                - `advancedSettingsName` · string · Optional — Name of the advanced settings configuration to apply to this transform's config. These configuration blocks are managed by MediaKind and you should not set this field unless MediaKind support has asked you to.
                - `config` · map from strings to any · **Required** — The configuration for the custom preset.
                  - `[any key]` · any — map of additional properties
                - `presetName` · string · **Required** — Name of this preset.
          - `relativePriority` · enum · Optional · _Defaults to Normal_ — Sets the relative priority of the TransformOutputs within a Transform
            - Allowed values: `High`, `Low`, `Normal`
    - `systemData` · object · Optional — Metadata pertaining to creation and last modification of the resource.
      - `createdAt` · string · **Required** · _format: date-time_ — The timestamp of resource creation (UTC).
      - `createdBy` · string · **Required** — The identity that created the resource.
      - `createdByType` · enum · **Required** — The type of identity that created the resource.
        - Allowed values: `User`, `Application`, `ManagedIdentity`, `Key`
      - `internalId` · string · **Required** · _format: uuid_ — The internal ID of the resource.
      - `lastModifiedAt` · string · **Required** · _format: date-time_ — The timestamp of resource last modification (UTC).
      - `lastModifiedBy` · string · **Required** — The identity that last modified the resource.
      - `lastModifiedByType` · enum · **Required** — The type of identity that last modified the resource.
        - Allowed values: `User`, `Application`, `ManagedIdentity`, `Key`
    - `type` · string · Optional — The type of the resource. E.g. "Microsoft.Media/mediaservices/assets"

Example:

```json
{
  "@odata.nextLink": "string",
  "supplemental": {
    "count": 0,
    "kind": "string",
    "operation": "string",
    "pagination": {
      "end": 0,
      "records": 0,
      "start": 0,
      "total": 0
    },
    "subscription": {
      "id": "string",
      "name": "string"
    }
  },
  "value": [
    {
      "id": "string",
      "name": "name",
      "properties": {
        "created": "2024-01-01T00:00:00Z",
        "description": "string",
        "lastModified": "2024-01-01T00:00:00Z",
        "outputs": [
          {
            "onError": "ContinueJob",
            "preset": {
              "@odata.type": "#Microsoft.Media.BuiltInStandardEncoderPreset",
              "advancedSettingsName": "string",
              "presetName": "string"
            },
            "relativePriority": "Normal"
          }
        ]
      },
      "systemData": {
        "createdAt": "2024-01-01T00:00:00Z",
        "createdBy": "string",
        "createdByType": "User",
        "internalId": "00000000-0000-0000-0000-000000000000",
        "lastModifiedAt": "2024-01-01T00:00:00Z",
        "lastModifiedBy": "string",
        "lastModifiedByType": "User"
      },
      "type": "string"
    }
  ]
}
```

### 400 — Bad Request

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 401 — Unauthorized

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 403 — Forbidden

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 404 — Not Found

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 429 — Too Many Requests

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 500 — Internal Server Error

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

---

Source spec: `media-api` · operationId: `[get]_/api/v1/projects/{project_name}/media/transforms`