API

Base URL

https://api.streamable.com/

Authentication

Authless

Unless otherwise noted, you can use the Streamable API without authentication. Unauthenticated requests are treated anonymously.

Basic

You should use basic authentication over HTTPS to upload videos to your Streamable account. If you don't have an account yet, you can sign up here.

Responses

All successful API responses have the application/json content type.

Errors

Errors are signaled in the response at a high level by HTTP status codes. Status codes in the 200 range are successful, codes in the 400 range indicate client errors, and codes in the 500 range indicate server errors.

Videos

Video resources represent an individual video on Streamable.

When a video is added to Streamable through the upload or import endpoints, a response is returned and processing happens in the background. Clients should then poll on the retrieve endpoint until the video is ready.

Video Schema

shortcode The unique identifier for the video.
title The title of the video.
status The upload status of the video.
0The video is being uploaded
1The video is being processed
2The video has at least one file ready
3The video is unavailable due to an error
files Multiple source files are generated for each video. You should generally serve the 'mp4' url to desktops and 'mp4-mobile' to mobile devices.
url The URL of the player page for the video.
thumbnail_url The URL of the thumbnail image for the video.

Example video

{
  "status": 2,
  "title": "Puppy!",
  "files": {
    "mp4": {
      "url": "//cdn.streamable.com/video/mp4/ifjh.mp4",
      "width": 848,
      "height": 480
    },
    "mp4-mobile": {
      "url": "//cdn.streamable.com/video/mp4-mobile/ifjh.mp4",
      "width": 360,
      "height": 636
    }
  },
  "url": "streamable.com/ifjh",
  "thumbnail_url": "//cdn.streamable.com/image/ifjh.jpg",
  "message": null
}

Upload a video file

Uploads a video file to Streamable. Video files must be smaller than 10GB in size and 10 minutes in length. Unauthenticated requests will be treated as anonymous uploads.

Returns a Video object on success, and an error otherwise.

Endpoint

POST https://api.streamable.com/upload

Arguments
file The video file to upload
title The title of the video Optional

Example upload request

curl https://api.streamable.com/upload \
  -u username:password \
  -F file=@myvideo.mp4

Example successful upload response

{
  "shortcode": "moo",
  "status": 1
}

Import a video from a URL

Imports a video to Streamable from a URL. The URL can be a direct link to a video file or to a web page containing a video. Video files must be smaller than 10GB in size and 10 minutes in length. Unauthenticated requests will be treated as anonymous uploads.

Returns a Video object on success, and an error otherwise.

Endpoint

GET https://api.streamable.com/import{?url}

Arguments
url The URL of the video to import
title The title of the video Optional

Example import request

curl https://api.streamable.com/import?url=https://archive.org/download/Windows7WildlifeSampleVideo/Wildlife.wmv \
  -u username:password

Example successful import response

{
  "shortcode": "moo",
  "status": 1
}

Retrieve a video

Retrieves a video that has previously been uploaded or imported.

Returns a Video object on success, and an error otherwise.

Endpoint

GET https://api.streamable.com/videos/{shortcode}

Arguments
shortcode The unique identifier for the video

Example video request

curl https://api.streamable.com/videos/moo

Example video response

{
  "status": 2,
  "title": "Puppy!",
  "files": {
    "mp4": {
      "url": "//cdn.streamable.com/video/mp4/ifjh.mp4",
      "width": 848,
      "height": 480
    },
    "mp4-mobile": {
      "url": "//cdn.streamable.com/video/mp4-mobile/ifjh.mp4",
      "width": 360,
      "height": 636
    }
  },
  "url": "streamable.com/ifjh",
  "thumbnail_url": "//cdn.streamable.com/image/ifjh.jpg",
  "message": null
}

oEmbed

Streamable videos support the oEmbed standard for embedding videos on websites.

Endpoint

GET https://api.streamable.com/oembed.json

Arguments
url The URL of the video to embed
maxwidth The maximum display width of the video Optional
maxheight The maximum display height of the video Optional

Discovery

Video pages on Streamable implement oEmbed discovery, with the type application/oembed+json.

Example oEmbed Request

curl https://api.streamable.com/oembed.json?url=https://streamable.com/ifjh
      

Example oEmbed Response

{
  "author_url": null,
  "height": 480,
  "html": "<div class=\"streamable-embed-container\" style=\"width: 100%; height: 0px; position: relative; padding-bottom: 56.338%;\"><iframe class=\"streamable-embed\" src=\"https://streamable.com/e/ifjh\" frameborder=\"0\" scrolling=\"no\" style=\"width: 100%; height: 100%; position: absolute;\" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe></div>",
  "provider_name": "Streamable",
  "provider_url": "https://streamable.com",
  "thumbnail_url": "//cdn.streamable.com/image/ifjh.jpg",
  "title": "Puppy!",
  "type": "video",
  "version": "1.0",
  "width": 848
}