Introduction

API Endpoint:

  https://apiv2.vlipsy.com

The Vlipsy API is a REST based interface that provides access to Vlipsy data and functionality. We use HTTP features like verbs, and response codes and return JSON in the response body for all API calls. We also implement CORS to allow interaction from a client-side web application.

Authentication

Example Request:

curl https://apiv2.vlipsy.com/v1/vlips/trending?\key=vl_hFxn07bG43d0n9t

Vlipsy uses API keys, and they are required for all endpoints. They should be passed as a query string parameter (i.e. https://apiv2.vlipsy.com/v1/vlips/trending?key=vl_hFxn07bG43d0n9t).

To receive an API key, please email us at api@vlipsy.com. We have provided a public key to be used in the following examples: vl_hFxn07bG43d0n9t.

Errors

The Vlipsy API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Malformed Request
401	Unauthorized -- Your API key is wrong
404	Not Found -- The specified vlip could not be found
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

Vlips

Vlip Object

Example Object

  {
      "id": "t4sf7Ofc",
      "title": "This pleases me",
      "from": "Heavyweights",
      "tags": [
          "heavyweights",
          "pleases me",
          "satisfied",
          "acceptable",
          "delight",
          "happy",
          "good news",
          "please",
          "im very pleased"
      ],
      "rating": "PG",
      "slug": "heavyweights-this-pleases-me-t4sf7Ofc",
      "duration": 4.7047,
      "media": {
          "mp4": {
              "url": "https://media.vlipsy.com/vlips/t4sf7Ofc/480p.mp4",
              "watermark": "https://media.vlipsy.com/vlips/t4sf7Ofc/480p-watermark.mp4",
              "width": 854,
              "height": 480
          },
          "preview_small": {
              "url": "https://media.vlipsy.com/vlips/t4sf7Ofc/preview-small.png",
              "gif": "https://media.vlipsy.com/vlips/t4sf7Ofc/preview-small.gif",
              "width": 256,
              "height": 144
          }
      },
  }

Attributes

Property	Type	Description
id	string	The id of the vlip
title	string	The title of the vlip
from	string	The property the vlip is from
tags	array	The tags relating to the vlip
rating	string	The MPAA rating of the content
slug	string	The slug of the vlip (for SEO)
duration	number	The duration (in seconds) of the vlip
media	object	outlined below

The media field is an object with many fields, each of which corresponds to an asset, and is an object in itself.

Media Object

Field	Purpose	Subfields
mp4	A large video version of the vlip.	url, watermark, width, height
mp4_small	A small video version of the vlip.	url, watermark, width, height
gif_email	A gif version of the vlip, perfect for putting in emails.	url, width, height
preview	An full-size image version (1280x720) of the vlip, best for previews when displaying multiple vlips.	url, width, height
preview_small	256x144 version of preview	url, gif, width, height
preview_xsmall	128px width preview. Gif under 50Kb	url, gif, width, height
preview_fixed_height	Same as preview, but with height fixed at 400 pixels.	url, gif, width, height
preview_fixed_height_small	Same as preview, but with height fixed at 200 pixels.	url, gif, width, height
preview_fixed_width	Same as preview, but with width fixed at 480 pixels.	url, gif, width, height
preview_fixed_width_small	Same as preview, but with width fixed at 240 pixels.	url, gif, width, height

What do the subfields of each media object mean?

Field	Meaning
url	The url of the corresponding media object.
gif	The url of a gif version of the vlip.
watermark	The url of the asset, with the Vlipsy watermark.
width	The width of the asset in pixels.
height	The height of the asset in pixels.

Search

GET /v1/vlips/search/q={search_term}

Example Request:

curl https://apiv2.vlipsy.com/v1/vlips/search?\q=heavyweights\&\key=vl_hFxn07bG43d0n9t

Example Response:

{
  "data": [
      {
          "id": "t4sf7Ofc",
          "title": "This pleases me",
          "from": "Heavyweights",
          "tags": [
              "heavyweights",
              "pleases me",
              "satisfied",
              "acceptable",
              "delight",
              "happy",
              "good news",
              "please",
              "im very pleased"
          ],
          "rating": "PG",
          "slug": "heavyweights-this-pleases-me-t4sf7Ofc",
          "duration": 4.7047,
          "media": {
              "mp4": {
                  "url": "https://media.vlipsy.com/vlips/t4sf7Ofc/480p.mp4",
                  "watermark": "https://media.vlipsy.com/vlips/t4sf7Ofc/480p-watermark.mp4",
                  "width": 854,
                  "height": 480
              },
              "preview_small": {
                  "url": "https://media.vlipsy.com/vlips/t4sf7Ofc/preview-small.png",
                  "gif": "https://media.vlipsy.com/vlips/t4sf7Ofc/preview-small.gif",
                  "width": 256,
                  "height": 144
              }
          },
      },
    {...},
    {...},
  ],
  "pagination": {
      "offset": 0,
      "count": 20,
      "total_count": 37
  },
}

Search all Vlips matching a text word or phrase. Words should be converted to lowercase and special characters should be stripped. Phrases should be url encoded. Ex. teddy%20bear

HTTP Request

GET https://apiv2.vlipsy.com/v1/vlips/search

Arguments

Parameter		Description
q	required	Search query word or phrase.
key	required	Your provided API key
limit	optional	Number of results to return (maximum 100, default 25)
pos	optional	Starting point for result set return (default 0)
safesearch	optional	The strength of the filter by rating. One of ['high', 'medium', 'low']

A note about safesearch: high corresponds to only G rated content, medium corresponds to G and PG rated content, low corresponds to G, PG, and PG-13 rated content, and if safesearch isn't defined, all content is permitted (including R-rated content).

Returns

A dictionary with a data property containing an array of vlips. Each entry in the array is a separate vlip object. Also returns a pagination property that contains the total count and other pagination information.

Vlip by ID

GET /v1/vlips/{ID}

Example Request:

curl https://apiv2.vlipsy.com/v1/vlips/wi3mmVSw?\key=vl_hFxn07bG43d0n9t

Example Response:

{
  "data": {
      "id": "wi3mmVSw",
      "source": "https://www.youtube.com/watch?v=XNdVyX1iGlE",
      "title": "Hey!  What a wonderful kind of day",
      "from": "Arthur",
      "tags": [
          "arthur",
          "mood",
          "hey",
          "good morning",
          "good day",
          "hello"
      ],
      "creator": {
          "_id": "57b5103a4d089f4c5d5f578e",
          "username": "gerrygarner",
          "display_name": "Gerry Garner",
          "avatar": "https://assets.vlipsy.com/avatars/57b5103a4d089f4c5d5f578e_46505.jpg"
      },
      "short_url": "https://vlp.to/wi3mmVSw",
      "created": "2017-11-16T12:56:46.415Z",
      "rating": "G",
      "slug": "arthur-hey-what-a-wonderful-kind-of-day-wi3mmVSw",
      "url": "https://vlipsy.com/vlip/arthur-hey-what-a-wonderful-kind-of-day-wi3mmVSw",
      "duration": 2.711042,
      "media": {
          "mp4": {...},
          "mp4_small": {...},
          "gif_email": {...},
          "preview": {...},
          "preview_small": {...},
          "preview_fixed_height_small": {...},
          "preview_fixed_height": {...},
          "preview_fixed_width_small": {...},
          "preview_fixed_width": {...}
      }
  }
}

Get details about a specific vlip by the unique vlip id.

HTTP Request

GET https://apiv2.vlipsy.com/v1/vlips/{id}

URL Parameters

Parameter	Description
id	The ID of the vlip to retrieve
key	Your provided API key

Notice that there are many more defined media fields on this call, as this call gives more flexibility into manipulating the media objects associated with the vlip.

GET /v1/vlips/trending

Example Request:

curl https://apiv2.vlipsy.com/v1/vlips/trending?\key=vl_hFxn07bG43d0n9t

Example Response:

{
  "data": [
    {
        "_id": "59b5d741655ada00073320fd",
        "id": "K26IVnoS",
        "title": "Heavy stuff (rain)",
        "from": "Caddy Shack",
        "tags": ["caddyshack","bill murray",...],
        "rating": "PG",
        "slug": "caddy-shack-heavy-stuff-rain-K26IVnoS",
        "duration": 8.1081,
        "media": {
            "mp4": {...},
            "preview_small": {...}
        }
    },
    {...},
    {...},
  ],
  "pagination": {
      "offset": 0,
      "count": 20,
      "total_count": 122
  }
}

Get a list of Trending Vlips.

HTTP Request

GET http://apiv2.vlipsy.com/v1/vlips/trending?limit=20&pos=2

Arguments

Parameter		Description
limit	optional	Number of results to return (maximum 100, default 25)
pos	optional	Starting point for result set return (default 0)
safesearch	optional	The strength of the filter by rating. One of ['high', 'medium', 'low']

Returns

Playlists

Get Playlists

GET /v1/playlists

Example Request:

curl https://apiv2.vlipsy.com/v1/playlists?\key=vl_hFxn07bG43d0n9t

Example Response

{
  "data": [
    {
        "title": "Hello",
        "image": "https://d050fb18391404b7878a-55f06a2c7c2d43d02d9dbec849c72a65.ssl.cf2.rackcdn.com/previews/w0XrPBAG_thumb.jpg",
        "id": "5N8mJ4Ub",
        "vlip_count": 209,
        "slug": "hello-5N8mJ4Ub",
        "created": "2018-02-23T16:01:47.544Z"
    },
    {
        "title": "Lol",
        "image": "https://d050fb18391404b7878a-55f06a2c7c2d43d02d9dbec849c72a65.ssl.cf2.rackcdn.com/previews/vlwRevXG_thumb.jpg",
        "id": "0pF2WCcQ",
        "vlip_count": 205,
        "slug": "Lol-0pF2WCcQ",
        "created": "2018-01-30T18:31:09.148Z"
    },
    {...},
    {...},
  ],
  "pagination": {
      "offset": 0,
      "count": 54,
      "total_count": 54
  }
}

Get back a list of all the playlists.

Arguments

Parameter		Description
limit	optional	Number of results to return (maximum 100, default 25)
pos	optional	Starting point for result set return (default 0)

Returns

A dictionary with a data property containing an array of playlists. Each entry contains data about the playlist. Also returns a pagination property that contains the total count and other pagination information.

Get a Playlist's Vlips

GET /v1/playlists/{ID}/vlips

Example Request:

  curl https://apiv2.vlipsy.com/v1/playlists/5N8mJ4Ub/vlips?\key=vl_hFxn07bG43d0n9t

Example Response:

{
  "data": [
    {
       "_id": "5a884cb7190f5e0009fba3d6",
       "id": "IZ2oIRev",
       "title": "What's up Doc?",
       "from": "Bugs Bunny",
       "tags": ["bugs bunny","whats up",...],
       "rating": "G",
       "slug": "bugs-bunny-whats-up-doc-IZ2oIRev",
       "duration": 6,
       "media": {
           "mp4": {...},
           "preview_small": {...}
       }
    },
    {...},
    {...},
  ],
  "pagination": {
      "offset": 0,
      "count": 20,
      "total_count": 209
  }
}

Pull back all vlips in that playlist.

HTTP Request

GET https://apiv2.vlipsy.com/v1/playlists/{id}/vlips?limit=20&key=vl_hFxn07bG43d0n9t

URL Parameters

Parameter		Description
id		The ID of the channel
limit	optional	Number of results to return (maximum 100, default 25)
pos	optional	Starting point for result set return (default 0)
safesearch	optional	The strength of the filter by rating. One of ['high', 'medium', 'low']