This endpoint allows you to get video details and upload new videos

Collection /video

Get video details
You can see and try a demo endpoint here as well as seeing all the error codes:

Apiary Demo

GET /video

Get details for all videos in account

  • sort_by - DEFAULT date_created, specify a field to sort by. Valid values are date_created | score | name
  • sort_order - DEFAULT ascending, specify a sort order. Valid values are ascending | descending
  • start - DEFAULT 1, specify a start index starts with 1
  • limit - DEFAULT 10, specify the number of results you want returned up to a limit of 20

item value
Access user | system
Full url https://api.buto.tv/v2/video/?sort_by={sort_by}&sort_order={sort_order}&start={start}&limit={limit}
verb GET
params string:sort_by string:sort_order int:start int:limit

Example usage

#get video details
curl -u API_KEY:x --include https://api.buto.tv/v2/video/?sort_by=date_created&sort_order=ascending&start=1&limit=10

returns

HTTP/1.1 200 OK
...
Content-Type: application/json

{
    "start": 1,
    "total_num_of_records":310,
    "videos":[{
        "video_id": "12345",
        "media_id": "NFSdb",
        "organisation_id": "Bt5xk",
        "video_title": "Test Video",
        "media_title": "Example video",
        ...
    },{
        "video_id": "56789",
        "media_id": "ASf3d",
        "organisation_id": "Bt5xk",
        "video_title": "Test Video 2",
        "media_title": "Example video 2",
        ...
    }]
}

GET /video/:id

Get details for a particular video.
- player_settings=true - DEFAULT false, this GET param will also return the player settings object for that video

item value
Access public
Full url https://api.buto.tv/v2/video/{id}
verb GET
params string:id OPTIONAL:?player_settings=true

Example usage

#get video details
curl --include https://api.buto.tv/v2/video/12345

returns

HTTP/1.1 200 OK
...
Content-Type: application/json


{
    "video_id": "12345",
    "media_id": "NFSdb",
    "organisation_id": "Bt5xk",
    "video_title": "Test Video",
    "media_title": "Brian's Buto",
    "description": "Brian Buto",
    "language": "en-GB",
    "published_width": "640",
    "published_height": "360",
    "enabled": "1",
    "duration": "130",
    "age_rating": "0",
    "category": "",
    "uri": {
        "poster_frame": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_frame_50.jpg",
        "thumbnail": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_thumbnail_large_50.jpg",
        "http": {
            "vp6_1200": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_1200.flv",
            "vp6_800": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_800.flv",
            "vp6_500": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_500.flv",
            "vp6_250": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_250.flv",
            "vp6_100": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_100.flv",
            "h264_1200": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_1200.mp4",
            "h264_800": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_800.mp4",
            "h264_500": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_500.mp4",
            "h264_360": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_360.mp4",
            "h264_250": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_250.mp4",
            "h264_100": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_100.mp4",
            "m4v_1024": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_iphone_1024.m4v",
            "m4v_256": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_iphone_256.m4v",
            "mobile_360": "https:\/\/d3lkew8zknjt1t.cloudfront.net\/butotv\/live\/videos\/Bt5xk\/1\/NFSdb\/NFSdb_360.3gp"
        }
    },
    "sharing": {
        "url": "",
        "text": "",
        "embed_within_facebook": "1"
    },
    "content_expiry": {
        "time": null,
        "message": ""
    },
    "tags": null,
    "captions": {
        "data": [{
            "caption_id": "cn9Cwym",
            "title": "Ali's Test",
            "language": "en-GB"
        }, {
            "caption_id": "cnBsjmq",
            "title": "English Captions",
            "language": "en-GB"
        }],
        "show_on_load": "0"
    },
    "overlays": [{
        "overlay_id": "iaWXJzh",
        "show": {
            "at_end": "0",
            "during": {
                "start": "00:11",
                "end": "00:15"
            }
        },
        "title": "345435",
        "description": "345345345",
        "image_path": "",
        "link_text": "345345345",
        "link_action": "javascript",
        "link_url": null,
        "link_target": null,
        "link_javascript_code": "",
        "language": "en-GB",
        "width": "100",
        "height": "30"
    }, {
        "overlay_id": "iaWXJzh",
        "show": {
            "at_end": "0",
            "during": {
                "start": "00:11",
                "end": "00:15"
            }
        },
        "title": "345435",
        "description": "345345345",
        "image_path": "",
        "link_text": "345345345",
        "link_action": "javascript",
        "link_url": null,
        "link_target": null,
        "link_javascript_code": "",
        "language": "en-GB",
        "width": "100",
        "height": "30"
    }],
    "languages": [{
        "code": "en-GB",
        "title": "English (United Kingdom)"
    }],
    "hd": {
        "allow": "0",
        "auto": "0"
    },
    "javascript_api": null,
    "security": {
        "token_required_platform": false,
        "is_ip_restricted": false
    },
    "metadata": "",
    "location": null,
    "analytics": null,
    "creator_id": "ABjLp",
    "created_at": "2012-11-12 09:51:30",
    "last_modified_by_id": "ABjLp",
    "last_modified_at": "2012-11-12 09:51:30",
    "setting_id": "sgf7tnY",
    "events_triggered_by_click": null,
    "status": {
        "status": "ok",
        "progress": 100,
        "code": 2000
    },
    "presentation_id": null,
    "monetization": null
}

PUT /video/:id

PUT (update) details for a particular video item

item value
Access system
Full url https://api.buto.tv/v2/video/{id}
verb PUT
params string:id:your video id mixed:data:{json assoc array: of your data}

DELETE /video/:id

Delete a video publish.

NB
- This endpoint is protected with an API key, SYSTEM ONLY
- Will not delete publish if it is the only publish of a video. You will be required to use DELETE /media/:id instead

  • id - int: the video_id you want to delete : REQUIRED

item value
Access system
Full url https://api.buto.tv/v2/video/{id}
verb DELETE
params int:id

Example

curl -X DELETE -u <your_api_key>:x --include https://api.buto.tv/v2/video/12345

returns

HTTP/1.1 200 OK
...
Content-Type: application/json

{"id":"12345", "result":true, "deleted":"2015-03-04 11:26:17"}

GET /video/:id/password/:password

Check to see if a password for a video is valid.
Buto allows clients to set a password on a video in the control panel. This password has to be entered into our video embeds before playback will be allowed.
NB This will not lock a video down to the CDN level and is merely meant to prevent embedded videos from being played back. For that level of security you'll need video access tokens.
We also recommend that you always use HTTPS with this endpoint so as not to send your passwords in plaintext.
NB Please note that we will not store the original password in our DB or logs, we'll do a hash compare and then discard the password

item value
Access public
Full url https://api.buto.tv/v2/video/{id}/password/{password}
verb GET
params string:id string:password

Example usage

Assuming that video 12345 has a password set of my_valid_password

curl --include https://api.buto.tv/v2/video/12345/password/my_valid_password

returns

HTTP/1.1 200 OK
...
Content-Type: application/json

[true]

Collection /video/organisation

To work with videos for an organisation

GET /video/organisation/{organisation_id}

Get all the videos for an organisation id

item value
Access user | system
Full url https://api.buto.tv/v2/video/organisation/{organisation_id}/{order_by}/{order_type}
verb GET
params string:your organisaton id OPTIONAL:string:Order videos by date_created|name|score defaults to date_created OPTIONAL:string:Order type |asc|desc defaults to desc

Collection /video/score

To work with video scoring which is typically used for ranking in automatic playlists by popularity

PUT /video/:id/score/{score}

PUT Update a video's score which is used for ranking in automatic playlists

item value
Access system
Full url https://api.buto.tv/v2/video/{id}/score/{score}
verb PUT
params string:id:your video id int:score:the score of your video

Collection /video/upload

To Upload a video to your account pragmatically
NB The url to the source video must be publicly available for our systems to pull from. Internal development, intranet and extranet addresses will not work.
NB The API key you use will determine which account the video is uploaded to.

POST /video/upload

Upload a new video to your account or replace an existing one:


Compulsory fields

You'll need these fields for a new upload or a replace
- The url of the source video
- The organisation_id of the organisation_id you're uploading from

New Video Fields

While uploading a new video you can also do the following:
- Set the Video name and description
- Set the Video publish internal title field which is for internal use in the control panel
- Set tags against the video NB Do not use spaces in your multiword tags, use hyphens
- Set the Video description_private field which will not be returned without a valid API key
- Set published_width and published_height
- Set theme_id and settings_id

Replace Video Fields

When replacing an existing video you must supply the following field, any other fields you set apart from the compulsory ones will be ignored
- the media_id of the existing video

item value
Access Client Key, System Key
Full url https://api.buto.tv/v2/video/upload/
verb GET
params as above

Example usage 1 - Upload a new video

#upload a new video        
    api_key=<your api key>       
    #NB we have to url encode our json string to use curl on the command line, so we use php/python/node for this purpose
    url_encoded=`php -r 'echo urlencode(json_encode({"name":"title","description":"public info about myvideo","description_private":"data that will not be returned by the public video api","url":"http://example.com/myvideo.mp4","organisation_id":"12345","tags":["soil-testing", "ph-neutral-crops","organic-potato-farming"]}));'`
    curl -X POST -u ${api_key}:x --data-binary "data=${url_encoded}" https://api.buto.tv/v2/video/upload

returns

HTTP/1.1 200 OK
...
Content-Type: application/json

{  
    "id":"zYsTq",
    "status":{  
        "status":"encoding",
        "progress":5,
        "code":2
    },
    "job_id":"a54bed10-089e-416f-a066-da775291e738",
    "action":"new video"
}

Example usage 2 - Replace an existing video/media

#replace an existing media of id 12345 
    api_key=<your api key>       
    #NB we have to url encode our json string to use curl on the command line, so we use php/python/node for this purpose
    url_encoded=`php -r 'echo urlencode(json_encode(["media_id"=>"12345","organisation_id"=>"Bbgwg","url"=>"http://example.com/myvideo_I_want_to_replace_with.mp4"]));'`
    curl -X POST -u ${api_key}:x --data-binary "data=${url_encoded}" https://api.buto.tv/v2/video/upload 

returns

HTTP/1.1 200 OK
...
Content-Type: application/json

{  
    "id":"12345",
    "status":{  
        "status":"encoding",
        "progress":5,
        "code":2
    },
    "job_id":"4e30ebdd-318f-4b31-892c-7ff4a7a47691",
    "action":"replace"
}

GET /video/upload

Uploads a new video using JSONP as Internet Explorer 9 is a pig.
This is very useful when you want to upload using pure client side javascript scenarios on rubbish browsers, such as single page apps.

  • data - a json object
  • callback - the callback function you wish to wrap the response
  • api_key - your api key

item value
Access SYSTEM KEYS ONLY
Full url https://api.buto.tv/v2/video/upload/?data={data}&callback={callback}&api_key={key}
verb GET
params string:data string:callback string:api_key

Example usage


function callback_buto (json) { // Do something with the JSON response }; // Create a new script element var script_element = document.createElement('script'); // Set its source to the JSONP API script_element.src = 'https://api.buto.tv/v2/video/upload/?data={"name":"title","description":"myvideo","url":"http://example.com/myvideo.mp4","organisation_id":"12345"}&callback=callback_buto&api_key=adjasdua0j9sjdaskf0FJKLDjklads0'; // Stick the script element in the page <head> document.getElementsByTagName('head')[0].appendChild(script_element);

returns

HTTP/1.1 200 OK
...
Content-Type: application/json

callback_buto({
    "id":"BsT3b",
    "code":1,
    "message":"waiting for encoding"
})

Collection /video/tag

To work with videos that have tags

GET /video/tag/:tag

GET a list of videos that use the specified tag(s).

NB

You can either pass in single tag or pass in a json formatted array of tags like : {"tags":["custom_tag_one","custom_tag_two"]}
If you're using curl on bash/zsh take care when you're escaping the json. On zsh it gets a bit intense and {"tags":["custom_tag_one","custom_tag_two"]} becomes "\{\"tags\":\[\"custom_tag_one\",\"custom_tag_two\"\]\}". Stick with postman when testing this endpoint.

item value
Access user
Full url https://api.buto.tv/v2/tag/{tag
verb GET
params string:tag: a single tag -or- string: tags:JSON array

Example usage

#get video ids for a single tag
curl -u API_KEY:x --include https://api.buto.tv/v2/video/tag/custom_tag_one

#-or-

#get video ids for multiple tags eg {"tags":["custom_tag_one","custom_tag_two"]}
curl -u API_KEY:x --include https://api.buto.tv/v2/video/tag/"\{\"tags\":\[\"custom_tag_one\",\"custom_tag_two\"\]\}"

returns

bash
HTTP/1.1 200 OK
...
Content-Type: application/json

[
    "12345",
    "56789",
    "DF7HD",
    "4FD7s"
]