API

Base URL

https://api.streamable.com/

Authentication

There are three ways to get started with the Streamable API.

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.

OAuth 2

OAuth 2 allow third party developers to access Streamable user accounts. If you're interested in implementing OAuth for your app, please email us with a brief description of the app and we'll get you set up.

Authorize Endpoint

https://streamable.com/oauth/authorize

Access Token Endpoint

https://streamable.com/oauth/access_token

OAuth Scopes
videos.manage Allows the app to manage user videos

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.

Developers should prefer to use our embed code for browser applications instead of constructing player tags and sources on their own.

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
}

Users

User resources represent individual users on Streamable.

User schema

bio The biography of the user
photo_url The URL of the avatar belonging to the user
user_name The name of the user

Example user

{
  "bio": "Jorts enthusiast",
  "photo_url": "//streamables.imgix.net/profile/Armen.png?fm=jpg",
  "user_name": "Armen"
}

Retrieve a user

Returns a User object representing the requested user on success, and an error otherwise.

Endpoint

GET https://api.streamable.com/users/{user_name}

Arguments
user_name The username of the desired user

Example user request

curl https://api.streamable.com/users/armen

Retrieve authenticated user

Returns a User object representing the currently authenticated user on success, and an error otherwise. Authentication is required.

Endpoint

GET https://api.streamable.com/me

Example me request

curl https://api.streamable.com/me \
  -u username:password

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
}