Skip to content

Storage API

Description

This section describes API methods for creating, deleting and changing files and directories in your storage and for creating and getting transcode tasks.

General information

  • Required headers: CDN-AUTH-TOKEN (authorization token, see Authorization)
  • Response Content-Type: application/json
  • All responses, including errors, has the body with the same structure: there always (except for 204 No Content) is status key; in case of success responses there is data key with response data where it is applicable, otherwise there might be description key with error description.
  • Possible status key values:

    Response code status
    200, 201 Completed
    202 Partially completed
    4xx, 5xx Some error value

Common errors

You can get one of the following errors as a result of any request:

Response code status description Description
401 Unauthorized Invalid token No token header provided
403 Forbidden No domain created Storage hasn't been initialized*
403 Forbidden Invalid account Wrong account in the provided URL
404 Not Found - Wrong URL
405 Method Not Allowed Method is not allowed You are not allowed to perform an action**
500 Internal Server Error - Internal server error

Attention

* - to initialize storage for your account you should make a POST request "Create file/directory" with any path
** - one of possible reasons - expired token (see Authorization)

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/files'

Error response example

{
  "status": "Unauthorized",
  "description": "Invalid token"
}

Files and directories

Get file/directory

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/files<path>

  • Request method: GET
  • Available querystring-parameters (work only when path is a directory):

    Parameter Possible values Description
    dirs_only empty string/1/true/0/false Get only children directories
    files_only empty string/1/true/0/false Get only children files
  • Possible response codes:

    Response code Response data Description
    200 Entity data -
    404 status: "Not Found" No entity under provided path
    422 status: "Unprocessable Entity" Errors in QS-parameters values (see description)
  • Entity (a file or a directory) data format:

    Key Description
    id Identifier
    name Name
    path Full path
    is_dir Whether an entity is a directory
    size Size in bytes
    content_type File Content-Type
    create_time Creation timestamp
    change_time Last change timestamp
    expiration_time Future removal timestamp
    download_url URL for downloading a file
    hls_url URL for watching a file in HLS (only for MP4 files)
    mpeg_dash_url URL for watching a file in MPEG-DASH (only for MP4 files)
    contents Directory children elements

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/files' -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed",
  "dirs_only": false,
  "files_only": false,
  "data": {
    "id": "606ef5635edc39a2f2832b7d",
    "name": "testaccount",
    "path": "/",
    "is_dir": true,
    "status": "",
    "size": 0,
    "content_type": "",
    "description": "12884901888",
    "create_time": 0,
    "change_time": 1641804692,
    "download_url": "",
    "contents": [
      {
        "id": "619e2531bc9fae0001083968",
        "name": "ansi_scte-35-2019a-1582645390859.pdf",
        "path": "/ansi_scte-35-2019a-1582645390859.pdf",
        "is_dir": false,
        "status": "ok",
        "size": 1633004,
        "content_type": "application/pdf",
        "description": "",
        "create_time": 1637754161,
        "change_time": 1637754161,
        "download_url": "https://prefix.a.trbcdn.net/cdn/testaccount/ansi_scte-35-2019a-1582645390859.pdf"
      },
      {
        "id": "617802e6cd0b6b1be6948e2b",
        "name": "road - 11018.mp4",
        "path": "/road - 11018.mp4",
        "is_dir": false,
        "status": "ok",
        "size": 54419074,
        "content_type": "video/mp4",
        "description": "",
        "create_time": 1635255020,
        "change_time": 1635255024,
        "download_url": "https://prefix.a.trbcdn.net/cdn/testaccount/road%20-%2011018.mp4",
        "hls_url": "https://prefix.a.trbcdn.net/cdn/testaccount/road%20-%2011018.mp4/playlist.m3u8",
        "mpeg_dash_url": "https://prefix.a.trbcdn.net/cdn/testaccount/road%20-%2011018.mp4/manifest.mpd"
      }
    ],
    "paging": {
      "count": 2,
      "count_on_page": 2
    }
  }
}

Error response example

{
  "status": "Unprocessable Entity",
  "description": {
    "files_only": [
      "Not a valid boolean."
    ]
  }
}

Create file/directory

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/files<path>

  • Request method: POST
  • Request body Content-Type: multipart/form-data (application/x-www-form-urlencoded is allowed when creating a directory)
  • Available parameters (mutually exclusive):

    Parameter Possible values Description
    file binary file contents File contents to put under path
    dir empty string/1/true/0/false Specifying that created path is a directory
  • Possible response codes:

    Response code Response data Description
    200 status: "Completed" Directory with the provided path exists*
    201 status: "Completed" Entity has been successfully created
    422 status: "Unprocessable Entity" Errors in parameters values (see description)

    Attention

    * - multiple attemps of creating files with the same path lead to the addition of numeric suffixes to their names

File creation request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/files/data.csv' -F "file=@data.csv" -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed"
}

Error response example

{
  "status": "Unauthorized",
  "description": "Invalid token"
}

Change file/directory

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/files<path>

  • Request method: PATCH
  • Request body Content-Type: application/json
  • Available parameters:

    Parameter Possible values Description
    name Valid string New entity name
    dir Valid string New parent directory path

    Valid string

    name might contain any symbols, except for :, ?, *, \, /, " and |.
    Example: new file (1).mp4.
    dir might contain any symbols, except for :, ?, *, \, " and |.
    Example: /new parent folder (1).

  • Possible response codes:

    Response code Response data Description
    200 status: "Completed" Entity has been successfully changed
    404 status: "Not Found" No entity under the provided path
    422 status: "Unprocessable Entity" Errors in parameters values (see description)

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/files/test_folder' -X PATCH --data '{"name": "test_folder2", "dir": "/new_parent_folder"}' -H "Content-Type: application/json" -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed"
}

Error response example

{
  "status": "Unprocessable Entity",
  "description": [
    "No data provided"
  ]
}

Delete file/directory

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/files<path>

  • Request method: DELETE
  • Possible response codes:

    Response code Response data Description
    204 Empty response Entity has been successfully deleted
    404 status: "Not Found" No entity under the provided path
    423 status: "Locked" Entity is locked*

    Attention

    * - either an entity is a file that is being written data into or a directory that contains such a file (see "DVR and stream recording")

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/files/test_folder' -X DELETE -H "CDN-AUTH-TOKEN: $TOKEN"

Error response example

{
  "status": "Locked",
  "description": "Entity is locked"
}

Space

Get allocated and used space

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/space

  • Request method: GET
  • Possible response codes:

    Response code Response data Description
    200 Space data -
  • Формат данных о пространстве:

    Ключ Description
    total Allocated space (in bytes)
    used Used space (in bytes)

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/space' -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed",
  "data": {
    "total": 12884901888,
    "used": 124670691
  }
}

Change allocated space

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/space

  • Request method: PATCH
  • Request body Content-Type: application/json
  • Available parameters:

    Parameter Possible values Description
    amount Integer New allocated space (in bytes)
  • Possible response codes:

    Response code Response data Description
    200 status: "Completed" Allocated space has been successfully changed
    202 status: "Partially completed" Notification to change allocated space has been sent to the manager
    400 description: "Amount is too big" amount value is too big
    400 description: "Amount is too small" amount value is smaller than used space
    422 status: "Unprocessable Entity" Errors in parameters values (see description)

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/space' -X PATCH --data '{"amount": 12884901889}' -H "Content-Type: application/json" -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed"
}

Error response example

{
  "status": "Bad Request",
  "description": "Amount is too small"
}

Transcode tasks

Get all transcode tasks

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/transcode

  • Request method: GET
  • Available querystring-parameters:

    Parameter Possible values Description
    start Valid datetime Start of tasks filter interval*
    end Valid datetime End of tasks filter interval*

    Valid datetime

    Datetime values (start, end) should be passed in YYYY-MM-DDThh:mm:ssZ format in UTC timezone.
    Example: 2021-12-30T12:30:05Z

    Attention

    * - tasks are filtered by creation datetime

  • Possible response codes:

    Response code Response data Description
    200 Tasks data -
    422 status: "Unprocessable Entity" Errors in QS-parameters values (see description)
  • Tasks data format:

    Key Description
    id Identifier
    status Completion status
    description Status description

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/transcode?start=2021-10-10T00:00:00Z&end=2022-10-10T00:01:02Z' -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed",
  "end": "2022-10-10T00:01:02Z",
  "start": "2021-10-10T00:00:00Z",
  "data": [
    {
      "id": "934136bf48c2412f9f1bb853f92a4c8a",
      "status": "Completed",
      "description": "Encoding video success."
    },
    {
      "id": "ba27bc62e9da46e48a406adabc50aec8",
      "status": "Completed",
      "description": "Encoding video success."
    }
  ]
}

Get specific transcode task

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/transcode/<task_id>

  • Request method: GET
  • Possible response codes:

    Response code Response data Description
    200 Task data -
  • Task data format:

    Key Description
    id Identifier
    status Completion status
    description Status description

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/transcode/ba27bc62e9da46e48a406adabc50aec8' -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed",
  "data": {
    "id": "ba27bc62e9da46e48a406adabc50aec8",
    "status": "Completed",
    "description": "Encoding video success."
  }
}

Get transcode presets

Transcode presets are the sets of audio- and videostreams parameters that transcoding output file should have.

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/transcode/presets

  • Request method: GET
  • Possible response codes:

    Response code Response data Description
    200 Presets data -

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/transcode/presets' -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed",
  "data": {
    "presets": [
      {
        "id": "5676a27cf9cb101634000002",
        "name": "Fixed iframes: 1080p - watermark",
        "container": "mp4",
        "video": {
          "codec": "H.264",
          "bit_rate": "5400",
          "fps": "30",
          "keyframes_max_dist": "150",
          "max_width": "1920",
          "max_height": "1080",
          "profile": "baseline",
          "level": "4",
          "sizing_policy": "ShrinkToFit",
          "padding_policy": "NoPad",
          "aspect_ratio": "auto"
        },
        "audio": {
          "codec": "AAC",
          "bit_rate": "160",
          "sample_rate": "44100",
          "channels": "2"
        },
        "watermarks": {
          "BottomLeft": {
            "horizontal_align": "Left",
            "horizontal_offset": "10%",
            "vertical_align": "Bottom",
            "vertical_offset": "10%",
            "height": "",
            "width": "",
            "max_height": "10%",
            "max_width": "10%",
            "opacity": "100",
            "sizing_policy": "ShrinkToFit"
          },
          "BottomRight": {
            "horizontal_align": "Right",
            "horizontal_offset": "10%",
            "vertical_align": "Bottom",
            "vertical_offset": "10%",
            "height": "",
            "width": "",
            "max_height": "10%",
            "max_width": "10%",
            "opacity": "100",
            "sizing_policy": "ShrinkToFit"
          },
          "Full": {
            "horizontal_align": "Left",
            "horizontal_offset": "0%",
            "vertical_align": "Top",
            "vertical_offset": "0%",
            "height": "",
            "width": "",
            "max_height": "100%",
            "max_width": "100%",
            "opacity": "100",
            "sizing_policy": "Fit"
          },
          "TopRight": {
            "horizontal_align": "Right",
            "horizontal_offset": "10%",
            "vertical_align": "Top",
            "vertical_offset": "10%",
            "height": "",
            "width": "",
            "max_height": "10%",
            "max_width": "10%",
            "opacity": "100",
            "sizing_policy": "ShrinkToFit"
          }
        },
        "standard": true,
        "tags": [
          "Popular 16:9"
        ]
      },
      ...
    ]
  }
}

Get transcode tasks stats

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/transcode/stats

  • Request method: GET
  • Available querystring-parameters:

    Parameter Possible values Description
    start Valid datetime Start of tasks filter interval*
    end Valid datetime End of tasks filter interval*

    Valid datetime

    Datetime values (start, end) should be passed in YYYY-MM-DDThh:mm:ssZ format in UTC timezone.
    Example: 2021-12-30T12:30:05Z

    Attention

    * - tasks are filtered by creation datetime

  • Possible response codes:

    Response code Response data Description
    200 Tasks statistics -
    422 status: "Unprocessable Entity" Errors in QS-parameters values (see description)
  • Tasks statistics format:

    Key Description
    transcode_operations Amount of completed transcode tasks
    transcode_minutes Length of tasks output files in minutes split by quality (SD, HD)

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/transcode/stats?start=2021-10-10T00:00:00Z&end=2022-10-10T00:01:02Z' -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed",
  "end": "2022-10-10T00:01:02Z",
  "start": "2021-10-10T00:00:00Z",
  "data": {
    "transcode_operations": 12,
    "transcode_minutes": {
      "SD": 14,
      "HD": 5
    }
  }
}

Create transcode task

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/transcode

  • Request method: POST
  • Request body Content-Type: application/json
  • Available parameters:

    Parameter Required Default value Possible values Description
    object_id Yes - File ID Identifier of the file to transcode (input file)
    presets Yes/No Empty list List of presets IDs Presets identifiers that the file should be transcoded into
    path No Input file directory Valid string Path where output files should be put
    delete_original No false Boolean Whether the input file should be deleted after task is completed
    start Yes/No 0 Integer (second) Start of the input file interval that should be transcoded
    duration Yes/No 0 Integer (seconds) Duration of the input file interval that should be transcoded
    send_email No false Boolean Whether to send an email notification on task completion

    presets, start and duration

    presets are required if neither start nor duration is set to a non-default value.
    start is required if neither presets nor duration is set to a non-default value.
    duration is required if neither presets nor start is set to a non-default value

    Valid string

    path validity check uses the same rule as the dir value check in Change file/directory

  • Possible response codes:

    Response code Response data Description
    201 task_id Task has been successfully created
    400 description: "Bad parameters" Failed to create a task with provided parameters
    404 description: "Object with object_id not found" Failed to find input file with provided object_id
    422 status: "Unprocessable Entity" Errors in parameters values (see description)

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/transcode' -X POST --data '{"object_id": "617602e6cd0a6b1be6948e2b", "path": "/new_folder", "start": 5, "duration": 4, "send_email": true}' -H "Content-Type: application/json" -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed",
  "data": {
    "task_id": "78e18299a591419fba61d7cab3ccf8b3"
  }
}

Qualities of a videofile

Common errors

You can get one of the following errors as a result of any request of this type:

Response code status description Description
404 Not Found File not found No file with file_id provided in the URL
404 Not Found Video not found No video with video_id provided in the URL

Get all qualities of a videofile

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/videos/<file_id>

  • Request method: GET
  • Possible response codes:

    Response code Response data Description
    200 Qualities list -
  • Quality data format:

    Key Description
    id File ID
    quality Quality name
    content_type File Content-Type
    advanced Advanced videofile data
    download_url URL for downloading a file
    hls_url* URL for watching a file in HLS
    mpeg_dash_url* URL for watching a file in MPEG-DASH

    Attention

    * - only for MP4 files longer than 10 seconds

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/videos/6244ab500e47cf10cbbae4a1' -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed",
  "data": [
    {
      "id": "6244ab500e47cf10cbbae4a0",
      "quality": "1080p",
      "content_type": "video/mp4",
      "size": 5636476,
      "advanced": {
        "audio_streams": [
          {
            "bit_rate": 256001,
            "channel_layout": "stereo",
            "channels": 2,
            "codec_long_name": "AAC (Advanced Audio Coding)",
            "codec_name": "aac",
            "codec_type": "audio",
            "duration": 6.016,
            "index": 1,
            "language": "und",
            "sample_rate": 48000
          }
        ],
        "format": {
          "bit_rate": 7465531,
          "duration": 6.04,
          "format_long_name": "QuickTime / MOV",
          "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
          "nb_streams": 2
        },
        "subtitle_streams": [],
        "video_streams": [
          {
            "bit_rate": 7198823,
            "codec_name": "h264",
            "codec_type": "video",
            "codeclongname": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
            "display_aspect_ratio": "16:9",
            "duration": 6.04,
            "fps": 50,
            "height": 1080,
            "index": 0,
            "width": 1920
          }
        ]
      },
      "download_url": "https://prefix.a.trbcdn.net/_video_/6244ab500e47cf10cbbae4a0/6244ab500e47cf10cbbae4a0.mp4"
    }
  ]
}

Add qualities to a videofile

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/videos/<file_id>

  • Request method: POST
  • Request body Content-Type: application/json
  • Available parameters:

    Parameter Possible values Description
    file_ids List of files IDs Videofiles to add to the target file
  • Possible response codes:

    Response code Response data Description
    200 status: "Completed" Videofiles have been successfully added
    422 status: "Unprocessable Entity" Errors in the parameter value (see description)

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/videos/6244ab500e47cf10cbbae4a1' -X POST --data '{"file_ids": ["6244ab500e47cf10cbbae4a2"]}' -H "Content-Type: application/json" -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed"
}

Error response example

{
  "status": "Unprocessable Entity",
  "description": {
    "file_ids": {
      "0": ["Not a valid string."]
    }
  }
}

Delete qualities of a videofile

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/videos/<file_id>

  • Request method: DELETE
  • Request body Content-Type: application/json
  • Available parameters:

    Parameter Required Default value Possible values Description
    ids Нет IDs of all qualities List of files IDs Qualities to delete
  • Possible response codes:

    Response code Response data Description
    204 status: "Completed" Qualities have been successfully deleted
    400 description: "Invalid videos list" Incorrect qualities IDs provided
    422 status: "Unprocessable Entity" Errors in the parameter value (see description)

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/videos/6244ab500e47cf10cbbae4a1' -X DELETE --data '{"ids": ["6244ab500e47cf10cbbae4a2"]}' -H "Content-Type: application/json" -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed"
}

Error response example

{
  "status": "Unprocessable Entity",
  "description": {
    "ids": {
      "0": ["Not a valid string."]
    }
  }
}

Get a quality of a videofile

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/videos/<file_id>/<video_id>

  • Request method: GET
  • Possible response codes:

    Response code Response data Description
    200 Quality data -
  • Quality data format:

    Key Description
    id File ID
    quality Quality name
    content_type File Content-Type
    advanced Advanced videofile data
    download_url URL for downloading a file
    hls_url* URL for watching a file in HLS
    mpeg_dash_url* URL for watching a file in MPEG-DASH

    Attention

    * - only for MP4 files longer than 10 seconds

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/videos/6244ab500e47cf10cbbae4a1/6244ab500e47cf10cbbae4a0' -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed",
  "data": {
    "id": "6244ab500e47cf10cbbae4a0",
    "quality": "1080p",
    "content_type": "video/mp4",
    "size": 5636476,
    "advanced": {
      "audio_streams": [
        {
          "bit_rate": 256001,
          "channel_layout": "stereo",
          "channels": 2,
          "codec_long_name": "AAC (Advanced Audio Coding)",
          "codec_name": "aac",
          "codec_type": "audio",
          "duration": 6.016,
          "index": 1,
          "language": "und",
          "sample_rate": 48000
        }
      ],
      "format": {
        "bit_rate": 7465531,
        "duration": 6.04,
        "format_long_name": "QuickTime / MOV",
        "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
        "nb_streams": 2
      },
      "subtitle_streams": [],
      "video_streams": [
        {
          "bit_rate": 7198823,
          "codec_name": "h264",
          "codec_type": "video",
          "codeclongname": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
          "display_aspect_ratio": "16:9",
          "duration": 6.04,
          "fps": 50,
          "height": 1080,
          "index": 0,
          "width": 1920
        }
      ]
    },
    "download_url": "https://prefix.a.trbcdn.net/_video_/6244ab500e47cf10cbbae4a0/6244ab500e47cf10cbbae4a0.mp4"
  }
}

Delete a quality of a videofile

URL: https://api.cdnvideo.ru/app/storage/v1/<your_account_name>/videos/<file_id>/<video_id>

  • Request method: DELETE
  • Request body Content-Type: application/json
  • Possible response codes:

    Response code Response data Description
    204 status: "Completed" Quality has been successfully deleted

Request example

curl 'https://api.cdnvideo.ru/app/storage/v1/testaccount/videos/6244ab500e47cf10cbbae4a1/6244ab500e47cf10cbbae4a0' -X DELETE -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "status": "Completed"
}