General Information

Base-URL for our API is https://api.vidcloud.is/v1 (note the 1 for version 1 behind the /)

All requests to the API shall be HTTP/1.1 GET

Please make sure to use the API with https only.

Most requests require a API Login & API Key, you can find both in the User Panel at the "User Settings" Tab.

Response is json, structure is as follows:

{
		"status": <status-code>,
		"msg": "<informational message. might vary, use the status code in your code!>",
		"result": <result of the request. varies depending on the request>
	}
	

status

200: Everything is OK. Request succeeded

400: Bad request (e.g. wrong parameters)

403: Permission denied (wrong api login/key, action on a file which does not belong to you, ...)

404: File not found

451: Unavailable For Legal Reasons

509: Bandwidth usage exceeded. Please try again later or use Browser Download. (you might see this during peak hours)

50x: Server errors. You should not see this, but be prepared.

msg

This message gives more detailed information in case there is an error.

You can use this for displaying it to the user, but please don't use it for checking if the request succeeded. That's what the status code is for.

result

holds the response of the request if succeeded. Might hold an array of data or just a boolean true/false, depending on the request

Account Infos

Everything account related (total used storage, reward, ...)

Request

https://api.vidcloud.is/v1/account/info?login={login}&key={key}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes

Response

200 (OK)
	Content-Type: application/json
{
    "status": 200,
    "msg": "OK",
    "result": {
        "extid": "5afff18c1d4ec",
        "email": "[email protected]",
        "signup_at": "2018-05-19 04:42:36",
        "storage_left": -1,
        "storage_used": "237285642",
        "storage_file": "7",
        "balance": 0
    }
}
	

File Info

check the status of a file, e.g. if the file exists

Request

https://api.vidcloud.is/v1/file/info?file={file}&login={login}&key={key}

Parameters

NameDescriptionExampleRequired
fileFile-ID(s), single file or comma-separated (max. 50)5b071514dd4ad,5b07151193091,5b07151193111yes
loginAPI-Login5afff18c1d5bcno
keyAPI-Key / API-PasswordCa89_D13-37a8BCAno

Response

200 (OK)
	Content-Type: application/json
{
		"status": 200,
		"msg": "OK",
		"result": {
        "5b071514dd4ad": {
            "id": "5b071514dd4ad",
            "status": 200,
            "name": "SampleVideo_360x240_30mb.mp4",
            "size": 37251992,
            "md5": "9372c9d4f05189b2efce927467060089",
            "content_type": "mp4"
        },
        "5b07151193091": {
            "id": "5b07151193091",
            "status": 451,
            "name": "example.mp4",
            "size": 30376392,
            "md5": "994970c3a79168f9b675858556da491b",
            "content_type": "mp4"
        },
        ,
        "5b07151193111": {
            "id": "5b07151193111",
            "status": 404,
            "name": false,
            "size": false,
            "md5": false,
            "content_type": false
        }
    }

Upload

Get an Upload URL

Uploads shall be POSTed to the upload URL returned by our API and shall be multipart/form-data encoded. Example with curl:

curl -F [email protected]/path/to/file.mp4 https://u-ant.betterstream.co/files/v1/upload/5b0cf236aab312

Request

https://api.vidcloud.is/v1/file/upload?login={login}&key={key}&folder={folder}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
folderFolder-ID to upload to1234no

Response

200 (OK)
	Content-Type: application/json
{
		"status": 200,
		"msg": "OK",
		"result": {
			"url": "https://u-ant.betterstream.co/files/v1/upload/5b0cf236aab312",
			"valid_until": "2015-01-09 00:02:50"
		}
	}

Add Remote Upload

Remote Uploading a file

Request

https://api.vidcloud.is/v1/remotedl/add?login={login}&key={key}&url={url}&folder={folder}&headers={headers}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
urlRemote URLhttp://google.com/favicon.icoyes
folderFolder-ID to upload to1234no
headersadditional HTTP headers, separated by newline (e.g. Cookies or HTTP Basic-Auth)User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:35.0) Gecko/20100101 Firefox/35.0
Cookie: auth=1234;
no

Response

200 (OK)
	Content-Type: application/json
{
    "status": 200,
    "msg": "OK",
    "result": {
        "id": "5b0cf408b038h",
        "folderid": "5b020f5562182"
    }
}

Check Remote Upload Status

Check Status of Remote Upload

Request

https://api.vidcloud.is/v1/remotedl/status?login={login}&key={key}&limit={limit}&id={id}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
limitMaximum number of results (Default: 5, Maximum: 100)5no
idRemote Upload ID1234no

Response

200 (OK)
	Content-Type: application/json
{
    "status": 200,
    "msg": "OK",
    "result": [
        {
            "id": "5b0cf408b098a",
            "folderid": "0",
            "remoteurl": "https://vidcloud.is/",
            "status": "new",
            "added": "2017-03-29 06:32:40",
            "last_update": "2017-03-29 06:32:40",
            "extid": false,
            "url": false
        },
        {
            "id": "5b0bc5a2ed0jn",
            "folderid": "0",
            "remoteurl": "http://proof.ovh.net/files/100Mio.dat",
            "status": "downloading",
            "added": "2017-03-28 09:02:26",
            "last_update": "2017-03-28 09:02:26",
            "extid": false,
            "url": false
        },
        {
            "id": "5b0bc5a2ed3km",
            "folderid": "0",
            "remoteurl": "http://google.de/example.mp4",
            "status": "finished",
            "added": "2017-03-28 09:02:26",
            "last_update": "2017-03-28 09:02:26",
            "extid": false,
            "url": false
        },
        {
            "id": "5b0bc5a2ed2kb",
            "folderid": "0",
            "remoteurl": "http://127.0.0.1/",
            "status": "error",
            "added": "2017-02-28 09:02:26",
            "last_update": "2017-02-28 09:02:26",
            "extid": false,
            "url": false
        }
    ]
}

List Folder

Shows the content of your folders

Request

https://api.vidcloud.is/v1/file/listfolder?login={login}&key={key}&folder={folder}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
folderFolder-ID5no

Response

200 (OK)
	Content-Type: application/json
{
        "status": 200,
        "msg": "OK",
        "result": {
            "folders": [
                {
                    "id": "5b020f461d09a",
                    "name": "video"
                },
                {
                    "id": "5b020f5562723",
                    "name": "sub"
                }
            ],
            "files": [
                {
                    "name": "big_buck_bunny.mp4.mp4",
                    "folder_id": "0",
                    "md5": "2a74c4181c65f6b86d452d955ca89d18",
                    "size": "33129367",
                    "status": "active",
                    "encode_status": "pending",
                    "content_type": "mp4",
                    "updated_at": 1527172792,
                    "download_count": 0,
                    "link": "https://vidcloud.is/v/5b0715086837c6/big_buck_bunny.mp4.mp4",
                    "linkextid": "5b071508687c6"
                },
                {
                    "name": "Sintel.2010.1080p.mkv.mp4",
                    "folder_id": "0",
                    "md5": "bcce86ad76f0daf39ba7ce39a40a575d",
                    "size": "30639964",
                    "status": "active",
                    "encode_status": "encoding",
                    "content_type": "mp4",
                    "updated_at": 1527172793,
                    "download_count": 0,
                    "link": "https://vidcloud.is/v/5b0715095285e/Sintel.2010.1080p.mkv.mp4",
                    "linkextid": "5b0715095285e"
                },
                {
                    "name": "SampleVideo_360x240_30mb.mp4",
                    "folder_id": "0",
                    "md5": "f9480cb83cd96eb5ce95df0fba58f9e0",
                    "size": "31539436",
                    "status": "active",
                    "encode_status": "finished",
                    "content_type": "mp4",
                    "updated_at": 1527172794,
                    "download_count": 0,
                    "link": "https://vidcloud.is/v/5b07150ae6ecb/SampleVideo_360x240_30mb.mp4",
                    "linkextid": "5b07150ae6ecb"
                },
                {
                    "name": "example.mp4",
                    "folder_id": "0",
                    "md5": "994970c3a79168f9b675858556da491b",
                    "size": "30376392",
                    "status": "disable",
                    "encode_status": "error",
                    "content_type": "mp4",
                    "updated_at": 1527172801,
                    "download_count": 0,
                    "link": "https://vidcloud.is/v/5b07151193020/example.mp4",
                    "linkextid": "5b07151193020"
                }
            ]
        }
    }

Create Folder

Create a new folder

Request

https://api.vidcloud.is/v1/file/createfolder?login={login}&key={key}&name={name}&parent_id={parent_id}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
namefolder namecreated%20by%20APIyes
parent_idParent-ID5b0cf568b12bcno

Response

200 (OK)
	Content-Type: application/json
{
    "status": 200,
	"msg": "OK",
	"result": {
         "id": "5b0cf568b038h",
         "name": "created by API"
     }
}

Rename Folder

Set a new name for a folders

Request

https://api.vidcloud.is/v1/file/renamefolder?login={login}&key={key}&folder={folder}&name={name}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
folderFolder-ID5b0cf568b12bcyes
namenew Folder-Namemy%20new%20foldernameyes

Response

200 (OK)
	Content-Type: application/json
{
    "status": 200,
	"msg": "OK",
	"result": true
}

Rename File

Set a new name for a file

Request

https://api.vidcloud.is/v1/file/rename?login={login}&key={key}&file={file}&name={name}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
fileFile IDUPPjeAk--30yes
namenew File-NameMy%20File%20Backup_2017.zipyes

Response

200 (OK)
	Content-Type: application/json
{
	  "status": 200,
	  "msg": "OK",
	  "result": true
	}

Copy File

Request

https://api.vidcloud.is/v1/file/copy?login={login}&key={key}&file={file}&folder={folder}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
fileFile IDUPPjeAk--30yes
folderFolder IDAkvhFG--31no

Response

200 (OK)
Content-Type: application/json
{
     "status": 200,
     "msg": "OK",
     "result": "UxxjeAk--50"
}

Delete File

Remove one of your files

Request

https://api.vidcloud.is/v1/file/delete?login={login}&key={key}&file={file}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
fileFile IDUPPjeAk--30yes

Response

200 (OK)
	Content-Type: application/json
{
	  "status": 200,
	  "msg": "OK",
	  "result": true
	}

Upload Subtitle

Get an Upload URL

Uploads shall be POSTed to the upload URL returned by our API and shall be multipart/form-data encoded. Example with curl:

curl -F [email protected]/path/to/file.srt https://r-butterfly.betterstream.co/subtitles/v1/upload/5b0cfe8e95985

Request

https://api.vidcloud.is/v1/subtitle/upload?login={login}&key={key}&file={file}&language={language}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
fileFile-ID to upload to1234yes
languageSubtitle languageEnglishyes List language

Response

200 (OK)
	Content-Type: application/json
{
        "status": 200,
        "msg": "OK",
        "result": {
            "data": {
                "url": "https://r-butterfly.betterstream.co/subtitles/v1/upload/5b0cfe8e95985",
                "valid_until": "2018-05-29 09:17:34"
            }
        }
    }

List Subtitle

Shows file's subtitles

Request

https://api.vidcloud.is/v1/subtitle/list?login={login}&key={key}&file={file}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
fileFile-IDAYgHe95d1E4yes

Response

200 (OK)
	Content-Type: application/json
{
        "status": 200,
        "msg": "OK",
        "result": [
            {
                "id": "5b0b8857784ab",
                "language": "Afar",
                "created_at": "2017-03-27 23:40:55",
                "file_id": "AYgHe95d1E4"
            },
            {
                "id": "5b0b8858935kf",
                "language": "English",
                "created_at": "2017-03-27 23:40:55",
                "file_id": "AYgHe95d1E4"
            }
        ]
    }

Get splash image

Shows the video splash image (thumbnail)

Request

https://api.vidcloud.is/v1/file/thumbnail?login={login}&key={key}&file={file}

Parameters

NameDescriptionExampleRequired
loginAPI-Login5afff18c1d5bcyes
keyAPI-Key / API-PasswordCa89_D13-37a8BCAyes
fileFile-IDAYgHe95d1E4yes

Response

200 (OK)
	Content-Type: application/json
{
        "status": 200,
        "msg": "OK",
        "result": "https://photo.vidcloudcdn.com/85/bd/df/75bddf58895ee9c0808fca32acea96c6/YvYcBn9mQXgIJG0MsUk2tWnCxRG4R2YKMIb6sQDa-thumbnails.jpg"
    }