REST API Examples

This page contains examples for specific actions using the REST API.

Read-only storage metadata fields

These fields are updated by the system and should not be modified.

  • health_status - Storage healthy status. true or false.
  • error_message - An error message.
  • files_total - The total number of files in this storage.
  • files_ingested - The total number of files in this storage that are already associated with assets.
  • space_used - The total number of bytes used by all files in this storage.
  • space_free - The number of bytes free.
  • refresh_timestamp - Timestamp of last refresh.

Writable storage metadata fields

These fields may be modified by an application.

  • name - A human readable name of the storage.
  • access:read - This storage may be read from. True by default.
  • access:write - This storage may be written to, e.g. files can be created or modified. False by default.
  • access:delete - Files in this storage may be deleted. False by default.
  • access:list - The content of this storage may be listed. True by default.
  • public_read - This storage is publicly accessible, e.g. no pre-signed urls must be generated. False by default.
  • public_url - The base HTTP/HTTPS url of this storage.
  • tag - Storage tags. Supports multiple entries.
  • lowres - Store lowres proxies in this storage.
  • marker_export - Store exported markers in this storage.
  • original - Store original files in this storage.
  • poster - Store posters in this storage.
  • poster_overlay - Store poster overlays in this storage.
  • sprite_map - Store spritemaps in this storage.
  • rekognition - Allow rekognition to be run on files from this storage.
  • refresh_interval - How often should this storage be traversed to find new files. Default is 0 (never).
Examples: "PT20.345S" -- parses as "20.345 seconds"
"PT15M"     -- parses as "15 minutes" (where a minute is 60 seconds)
"PT10H"     -- parses as "10 hours" (where an hour is 3600 seconds)
"P2D"       -- parses as "2 days" (where a day is 24 hours or 86400 seconds)
"P2DT3H4M"  -- parses as "2 days, 3 hours and 4 minutes"
  • auto_ingest:* - There are multiple metadata keys that control Auto Ingest. See Auto Ingest page for details.

Fields specific for AWS_S3 and AWS_GLACIER type storages
* aws:region - The AWS region of the S3 bucket.
* aws:profile - The AWS profile to use when accessing this storage.
* aws:access_key_id - The AWS IAM access key ID to use when accessing this storage.
* aws:secret_access_key - The AWS IAM secret access key to use when accessing this storage.

To use server credentials
 - set `aws:access_key_id` and `aws:secret_access_key` to `null`.
 - set `public_read` to false.

Fields specific for AWS_S3 type storages
* aws:sse_algorithm - The algorithm to use when server side encryption is active.
* aws:kms_cmk_id - The master key id to use when server side encryption is active.

Fields specific for AZURE_BLOB type storages
* azure:account_name - Name of account.
* azure:account_key - Key of account.

Create Amazon S3 storage

POST /storage
{
    "type": "AWS_S3",
    "uri": "s3://accurate-video-bucket"
    "metadata": [
        {
            "key": "name",
            "value": "Test storage"
        },
        {
            "key": "refresh_interval",
            "value": "PT15M"
        },
        {
            "key": "tag",
            "value": "original"
        },
        {
            "key": "tag",
            "value": "rekognition"
        },
        {
            "key": "aws:region",
            "value": "eu-central-1"
        },
        {
            "key": "access:public_read",
            "value": "false"
        }
    ]
}

See Writable storage metadata fields for all available metadata options.

Create Azure blob storage

POST /storage
{
    "type": "AZURE_BLOB",
    "uri": "blob://accurate-video-container"
    "metadata": [
        {
            "key": "name",
            "value": "Test storage"
        },
        {
            "key": "refresh_interval",
            "value": "PT15M"
        },
        {
            "key": "tag",
            "value": "original"
        },
        {
            "key": "azure:account_name",
            "value": "account-name"
        },
        {
            "key": "azure:account_key",
            "value": "account-key"
        }
    ]
}

See Writable storage metadata fields for all available metadata options.

Create local storage

For a local storage, you need to provide a local uri and a public url to a mount point.

POST /storage
{
    "type": "LOCAL",
    "uri": "/absolute/mount/point"
    "metadata": [
        {
            "key": "name",
            "value": "Test storage"
        },
        {
            "key": "refresh_interval",
            "value": "PT15M"
        },
        {
            "key": "tag",
            "value": "original"
        },
        {
            "key": "public_url",
            "value": "https://www.example.com/storage"
        }
    ]
}

See Writable storage metadata fields for all available metadata options.

Source and destination storages

A source storage should be read-only, containing nothing but original files. This should first of all be enforced at its source, e.g. setting the actual S3 bucket as read-only.

Protect the storage by setting metadata tag access:write to false.

PUT /storage/{storageId}/metadata
[
    {
        "key": "access:write",
        "value": "false"
    }
]

This will prevent AV from writing lowres proxies, spritemaps, posters etc to the storage.

A destination storage should allow these actions by setting access:write to true (which is the default) and adding appropriate tags e.g.

PUT /storage/{storageId}/metadata
[
    {
        "key": "access:write",
        "value": "true"
    },
    {
        "key": "key",
        "value": "lowres"
    },
    {
        "key": "key",
        "value": "marker_export"
    },
    {
        "key": "key",
        "value": "poster"
    },
    {
        "key": "key",
        "value": "poster_overlay"
    },
    {
        "key": "key",
        "value": "sprite_map"
    }
]

See Writable storage metadata fields for all available options.

Configure automatic ingest for a storage

Automatic ingest is configured by a specific set of storage metadata. See Auto Ingest for details and explanations.

The following example updates an existing storage but can of course be applied on storage creation as well.

PUT /storage/{storageId}/metadata
[
    {
        "key": "auto_ingest:enabled",
        "value": "true"
    },
    {
        "key": "auto_ingest:include",
        "value": "incoming/*"
    },
    {
        "key": "auto_ingest:manifest:enabled",
        "value": "true"
    },
    {
        "key": "auto_ingest:manifest:include",
        "value": "manifest/*.json"
    }
]

This enables auto ingest for all files uploaded to the incoming/ path and manifest ingest to all JSON files uploaded to the
manifest/ path.

Files can be located using wildcard serches on file name.

GET /storage/{storage id}/file?search=*.mp4

Output:

{
    "values": [
        {
            "fileLocations": [
                {
                    "fileName": "1463dfc3-ec9a-497e-b11a-d08c55d354ab/7015f72f-4cd5-4a6c-8edc-bd78ef2d4050_Video.mp4",
                    "fileSize": 29895620,
                    "uri": "s3://accurate-player/1463dfc3-ec9a-497e-b11a-d08c55d354ab/7015f72f-4cd5-4a6c-8edc-bd78ef2d4050_Video.mp4"
                }
            ],
            "id": "101"
        },
        {
            "fileLocations": [
                {
                    "fileName": "1463dfc3-ec9a-497e-b11a-d08c55d354ab/f0e446ec-534b-4b81-8457-35c9a2e64d91_Audio.mp4",
                    "fileSize": 1763417,
                    "uri": "s3://accurate-player/1463dfc3-ec9a-497e-b11a-d08c55d354ab/f0e446ec-534b-4b81-8457-35c9a2e64d91_Audio.mp4"
                }
            ],
            "id": "204"
        }
    ]
}

Retrieve all timespan markers

This will return all timespan markers for the asset.

GET /asset/{assetId}/timespan

Retrieve all timespan markers of specific types

All timespan markers have a type. This request will return all timespan objects having type "Baton" or "Manual".

GET /asset/{assetId}/timespan?type=Baton&type=Manual

Ingest one or more files and create an asset

Several files of different types can be ingested together and combine a new asset using the endpoint

POST /asset

This action starts an ingest job in the background, and will return the job id. The ingest job will
- extract media info, storing it as file metadata
- perform heavy operations like transcoding (creating proxy files) and creating sprite maps.

To get information about the progress of the job, use the endpoint

GET /job/{job-id}

Ingest a file using type AUTO

First locate the files that should be added to the asset, e.g. using search filter

POST /asset

{
   "files" : [
      {
         "id" : "112",
         "type" : "AUTO"
      }
   ],
   "metadata" : [
      {
         "key" : "title",
         "value" : "My new asset"
      }
   ]
}

The type for the file can be one of:
- AUTO
- VIDEO
- AUDIO
- SUBTITLE
- BATON
- STILL_FRAME

The system will make it's best effort to try to guess the type if AUTO is given.

Ingest multiple files

First locate the files that should be added to the asset, e.g. using search filter

POST /asset
{
   "files" : [
      {
         "id" : "98",
         "metadata" : [
            {
               "key" : "tag",
               "value" : "lowres"
            }
         ],
         "type" : "VIDEO"
      },
      {
         "id" : "1031",
         "metadata" : [
            {
               "key" : "tag",
               "value": "mp4-6track"
            }
         ],
         "type" : "AUDIO"
      },
      {
         "id" : "742",
         "metadata" : [
            {
               "key" : "language",
               "value" : "ger" 
            }
         ],
         "type" : "SUBTITLE"
      }
   ],
   "metadata" : [
      {
         "key" : "title",
         "value" : "My new asset"
      }
   ]
}
  • the video file is tagged with lowres indicating that this is a proxy file
  • the audio file is tagged with mp4-6track indicating that this file has 6 channels.
  • language metadata is added to indicate that it is a German subtitle file.

Ingest an asset without running transcode

If you ingest files already in a format supported by browsers, there is no need to transcode new proxies.

First locate the files that should be added to the asset, e.g. using search filter

Then, create the asset.

POST /asset?skip_transcode=true
{
    "metadata": [
        {
            "key": "title",
            "value": "My awesome asset"
        }
    ],
    "files": [
        {
            "id": "101",
            "type": "VIDEO",
            "metadata": [
                {
                    "key": "tag",
                    "value": "mp4_lowres"
                }
            ]
        },
        {
            "id": "204",
            "type": "AUDIO",
            "metadata": [
                {
                    "key": "tag",
                    "value": "aac_surround_5.1"
                },
                {
                    "key": "language",
                    "value": "en_US"
                }
            ]
        }
    ]
}

The ingest job will perform all the operations explained here but it will skip the transcode job, significatly increating the speed of the ingest.

Create an asset without running a job

Assets can be created without executing a job.

First locate the files that should be added to the asset, e.g. using search filter

Then, create the asset.

POST /asset?skip_ingest=true
{
    "metadata": [
        {
            "key": "title",
            "value": "My awesome asset"
        }
    ],
    "files": [
        {
            "id": "101",
            "type": "VIDEO",
            "metadata": [
                {
                    "key": "tag",
                    "value": "mp4_lowres"
                }
            ]
        },
        {
            "id": "204",
            "type": "AUDIO",
            "metadata": [
                {
                    "key": "tag",
                    "value": "aac_surround_5.1"
                },
                {
                    "key": "language",
                    "value": "en_US"
                }
            ]
        }
    ]
}

Output. Note that the asset will contain no sprite maps, and the files will have no media information like frame rate.

{
    "creationDate": "2020-11-27T13:23:50.782712Z",
    "files": [
        {
            "assetId": "5655",
            "creationDate": "2020-11-27T13:05:03.902Z",
            "fileLocations": [
                {
                    "fileId": "101",
                    "fileName": "1463dfc3-ec9a-497e-b11a-d08c55d354ab/7015f72f-4cd5-4a6c-8edc-bd78ef2d4050_Video.mp4",
                    "fileSize": 29895620,
                    "uri": "s3://accurate-player/1463dfc3-ec9a-497e-b11a-d08c55d354ab/7015f72f-4cd5-4a6c-8edc-bd78ef2d4050_Video.mp4",
                    "url": "https://accurate-player.s3.eu-central-1.amazonaws.com/1463dfc3-ec9a-497e-b11a-d08c55d354ab/7015f72f-4cd5-4a6c-8edc-bd78ef2d4050_Video.mp4"
                }
            ],
            "fileName": "1463dfc3-ec9a-497e-b11a-d08c55d354ab/7015f72f-4cd5-4a6c-8edc-bd78ef2d4050_Video.mp4",
            "id": "101",
            "metadata": [
                {
                    "creationDate": "2020-11-27T13:05:03.903Z",
                    "id": "111",
                    "key": "aws:etag",
                    "updateDate": "2020-11-27T13:05:03.903Z",
                    "value": "d467becb0c0874333f541b83450d9ebc-3"
                },
                {
                    "creationDate": "2020-11-27T13:23:50.785211Z",
                    "id": "5516",
                    "key": "tag",
                    "updateDate": "2020-11-27T13:23:50.785211Z",
                    "value": "mp4_lowres"
                }
            ],
            "storageId": "21",
            "type": "VIDEO",
            "updateDate": "2020-11-27T13:23:50.791846Z",
            "uri": "s3://accurate-player/1463dfc3-ec9a-497e-b11a-d08c55d354ab/7015f72f-4cd5-4a6c-8edc-bd78ef2d4050_Video.mp4",
            "url": "https://accurate-player.s3.eu-central-1.amazonaws.com/1463dfc3-ec9a-497e-b11a-d08c55d354ab/7015f72f-4cd5-4a6c-8edc-bd78ef2d4050_Video.mp4"
        },
        {
            "assetId": "5655",
            "creationDate": "2020-11-27T13:05:03.902Z",
            "fileLocations": [
                {
                    "fileId": "204",
                    "fileName": "1463dfc3-ec9a-497e-b11a-d08c55d354ab/f0e446ec-534b-4b81-8457-35c9a2e64d91_Audio.mp4",
                    "fileSize": 1763417,
                    "uri": "s3://accurate-player/1463dfc3-ec9a-497e-b11a-d08c55d354ab/f0e446ec-534b-4b81-8457-35c9a2e64d91_Audio.mp4",
                    "url": "https://accurate-player.s3.eu-central-1.amazonaws.com/1463dfc3-ec9a-497e-b11a-d08c55d354ab/f0e446ec-534b-4b81-8457-35c9a2e64d91_Audio.mp4"
                }
            ],
            "fileName": "1463dfc3-ec9a-497e-b11a-d08c55d354ab/f0e446ec-534b-4b81-8457-35c9a2e64d91_Audio.mp4",
            "id": "101",
            "metadata": [
                {
                    "creationDate": "2020-11-27T13:05:03.903Z",
                    "id": "111",
                    "key": "aws:etag",
                    "updateDate": "2020-11-27T13:05:03.903Z",
                    "value": "d41d8cd98f00b204e9800998ecf8427e-2"
                },
                {
                    "creationDate": "2020-11-27T13:23:50.785211Z",
                    "id": "5516",
                    "key": "tag",
                    "updateDate": "2020-11-27T13:23:50.785211Z",
                    "value": "aac_surround_5.1"
                },
                {
                    "creationDate": "2020-11-27T13:23:50.785211Z",
                    "id": "5517",
                    "key": "language",
                    "updateDate": "2020-11-27T13:23:50.785211Z",
                    "value": "en_US"
                }
            ],
            "storageId": "21",
            "type": "AUDIO",
            "updateDate": "2020-11-27T13:23:50.791846Z",
            "uri": "s3://accurate-player/1463dfc3-ec9a-497e-b11a-d08c55d354ab/f0e446ec-534b-4b81-8457-35c9a2e64d91_Audio.mp4",
            "url": "https://accurate-player.s3.eu-central-1.amazonaws.com/1463dfc3-ec9a-497e-b11a-d08c55d354ab/f0e446ec-534b-4b81-8457-35c9a2e64d91_Audio.mp4"
        }
    ],
    "id": "5655",
    "metadata": [
        {
            "creationDate": "2020-11-27T13:23:50.782793Z",
            "id": "5668",
            "key": "title",
            "updateDate": "2020-11-27T13:23:50.782793Z",
            "value": "My awesome asset"
        }
    ],
    "updateDate": "2020-11-27T13:23:50.791816Z"
}

Ingest file with access configured

Access can be defined on asset creation.

First locate the files that should be added to the asset, e.g. using search filter

POST /asset

{
  "files": [
    {
      "id": "112",
      "type": "AUTO"
    }
  ],
  "metadata": [
    {
      "key": "title",
      "value": "Asset with access preconfigured"
    }
  ],
  "access": [
    {
      "entries": [
        {
          "accessTypes": ["read"],
          "filters": []
        }
      ],
      "principals": [
        {
          "identifier": "restricted-user",
          "principalType": "USER"
        }
      ]
    },
    {
      "entries": [
        {
          "accessTypes": ["read", "modify_all_access", "write"],
          "filters": []
        }
      ],
      "principals": [
        {
          "identifier": "admin-user",
          "principalType": "USER"
        }
      ]
    }
  ]
}

For more information and examples, see Access Documentation

Update access for an asset

Access can be updated for an existing asset.

NOTE This will replace the current access configuration entirely.

POST /asset/{assetId}/access
[
  {
    "entries": [
      {
        "accessTypes": ["read"],
        "filters": []
      }
    ],
    "principals": [
      {
        "identifier": "restricted-user",
        "principalType": "USER"
      }
    ]
  },
  {
    "entries": [
      {
        "accessTypes": ["read", "modify_all_access", "write"],
        "filters": []
      }
    ],
    "principals": [
      {
        "identifier": "admin-user",
        "principalType": "USER"
      }
    ]
  }
]

For more information and examples, see Access Documentation

AV Asset View Userguide Automatic Ingest