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 isdata
key with response data where it is applicable, otherwise there might bedescription
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 big400 description: "Amount is too small" amount
value is smaller than used space422 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 inYYYY-MM-DDThh:mm:ssZ
format in UTC timezone.
Example: 2021-12-30T12:30:05ZAttention
* - 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 - 404 status: "Task not found" No task with task_id
provided in the URL422 status: "Unprocessable Entity" Errors in task_id
value (seedescription
) -
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 inYYYY-MM-DDThh:mm:ssZ
format in UTC timezone.
Example: 2021-12-30T12:30:05ZAttention
* - 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 neitherstart
norduration
is set to a non-default value.
start
is required if neitherpresets
norduration
is set to a non-default value.
duration
is required if neitherpresets
norstart
is set to a non-default valueValid string
path
validity check uses the same rule as thedir
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" }