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

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

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