API Reference

Welcome to the VidGrid API! This is a simple REST API that you can use to record and/or upload videos into your VidGrid account. All requests should be made over SSL and all responses are JSON encoded.

You can view code examples in the area to the right, and you can switch the language of the examples with the tabs in the top right.

Help and Support

If you discover a mistake in the documentation, please report an issue and we'll take a look.

If you need further assistance or have any other questions, please visit our Help Center.

Authentication

Authentication by passing api_key as a parameter. Be sure to replace {key} with your API key.

curl -X POST \
  'https://api.vidgrid.com/v1/token/record' \
  -d 'api_key={key}'

require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v1/token/record")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request.body = "api_key={key}"

response = http.request(request)
puts response.read_body

import requests

url = "https://api.vidgrid.com/v1/token/record"

payload = "api_key={key}"
headers = {}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

var settings = {
  "url": "https://api.vidgrid.com/v1/token/record",
  "method": "POST",
  "data": {
    "api_key": "{key}"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Authentication is done via an API key found in your VidGrid account's integration settings.

Under integration settings you can copy your API keys or roll new ones if desired.

The API key should be passed as a parameter with all API requests to the server.

API Key Types

User	Use for the our Recording API and Uploading API. Videos uploaded with a User API key will be uploaded to that user's VidGrid account.
Organization	Use for the our Recording API and Uploading API. Videos uploaded with an Organization API key will be upload to the organization's VidGrid account. These videos will not have an owner by default.

Recording API

The Recording API allows you to record videos using the VidGrid Screen Recorder. A basic implementation is as follows:

1. Request a record token from VidGrid
2. Display a record button to a user using the either recordButtonIframe or recorderLaunchURI returned in Step 1. (We recommend using the iframe since it handles downloading and installing the recorder for first time users)
3. Wait for a response at your Webook endpoint and use the video data as you wish (eg. embed the video in a support ticket)

Get Record Token

Example Request

curl -X POST \
  'https://api.vidgrid.com/v1/token/record' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key" : "{key}",
    "video_endpoint" : "https://yoursite.com/endpoint",
    "video_set_public" : true
  }'

require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v1/token/record")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = '{
  api_key: "{key}",
  video_endpoint: "https://yoursite.com/endpoint",
  video_set_public: true
}'

response = http.request(request)
puts response.read_body

import requests

url = "https://api.vidgrid.com/v1/token/record"

payload = {
  'api_key': "{key}",
  'video_endpoint': "https://yoursite.com/endpoint",
  'video_set_public': true
}

headers = {
  'Content-Type': "application/json",
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

var settings = {
  "url": "https://api.vidgrid.com/v1/token/record",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
  },
  "data": {
    api_key: "{key}",
    video_endpoint: "https://yoursite.com/endpoint",
    video_set_public: true
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Example Response

{
  "worked": true,
  "video_endpoint": "https://yoursite.com/endpoint",
  "video_endpoint_extras": null,
  "video_set_public": true,
  "token": "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789",
  "recorderDownloadUrl": "https://app.vidgrid.com/recorder/download/ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789",
  "recorderLaunchURI": "ilosrecord:record?token=ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789",
  "recordButtonIframe": "<iframe src='https://app.vidgrid.com/embed/api/recorder/ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789'></iframe>",
  "expires": 1527729792
}

expires is a UNIX Timestamp (UTC) indicating when the temporary token will expire

This endpoint returns a one-time record token, ways to display a record button, and some additional data you can see in the sample response to the right.

HTTP Request

POST https://api.vidgrid.com/v1/token/record

Parameters

api_key string	A User or Organization API key from your VidGrid account.
service_name optional string	The name of your service. Mostly used for informational purposes.
video_endpoint optional string	The Webook URL endpoint where a POST will be made after a video has been recorded and uploaded.
video_endpoint_trigger optional string	Determines when to trigger the Webook. The default is ON_UPLOAD_COMPLETE which happens as soon as a video has been uploaded to VidGrid. The other option is ON_PROCESSING_COMPLETE which happens when a video has completed processing and is watchable on VidGrid.
video_endpoint_extras optional array	An array of extra data that will be sent to the Webook endpoint.
auto_open_video optional boolean	Whether or not to automatically open the video in the user's browser after recording.
auto_close_recorder optional boolean	Whether or not to close the recorder when it is finished uploading the video. If set to true, the user will only be able to record one video with this token.
request_video_title optional boolean	Whether or not to have the user title the video after recording.
record_single_video optional boolean	deprecated This option has been deprecated and effectively sets auto_open_video = false, auto_close_recorder = true, and request_video_title = false. These three options should be used explicitly in favor of record_single_video.
video_title optional string	Used to give the video a title if request_video_title is set to false.
video_set_public optional boolean	When set to true, an uploaded video will be viewable by anyone with a link. If set to false, a user must be logged in to your VidGrid account to view the video. If not set, your user or organization defaults will be used.
collection optional string	Automatically add the uploaded video to a folder. Note: Collections are now called Folders in app.
auto_download_recorder optional boolean	Whether or not to download the recorder without redirecting to the install recorder page. This happens the first time a use clicks record when using the iframe method.
auto_authenticate_on_install optional boolean	Whether or not a user should be automatically authenticated the first time the recorder is launched after install. If set to false, the user will need to return to their browser and click record in order to be authenticated.
auto_launch_fullscreen optional boolean	Whether or not the recorder should launch in fullscreen mode by default.
webcam_only optional boolean	Whether or not the recorder should launch in webcam only mode. The user will not be able to turn off webcam only.

Uploading API

The Uploading API allows you to upload videos using a web uploader in an iframe. A basic implementation is as follows:

1. Request an upload token from VidGrid
2. Display an upload form to a user using the either uploadIframe or uploadIframeBasic returned in Step 1.
3. Wait for a response at your Webook endpoint and use the video data as you wish (eg. embed the video in a support ticket)

Get Upload Token

Example Request

curl -X POST \
  'https://api.vidgrid.com/v1/token/upload' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key" : "{key}",
    "video_endpoint" : "https://yoursite.com/endpoint",
    "video_set_public" : true
  }'

require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v1/token/upload")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = '{
  api_key: "{key}",
  video_endpoint: "https://yoursite.com/endpoint",
  video_set_public: true
}'

response = http.request(request)
puts response.read_body

import requests

url = "https://api.vidgrid.com/v1/token/upload"

payload = {
  'api_key': "{key}",
  'video_endpoint': "https://yoursite.com/endpoint",
  'video_set_public': true
}

headers = {
  'Content-Type': "application/json",
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

var settings = {
  "url": "https://api.vidgrid.com/v1/token/upload",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
  },
  "data": {
    api_key: "{key}",
    video_endpoint: "https://yoursite.com/endpoint",
    video_set_public: true
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Example Response

{
  "worked": true,
  "video_endpoint": "https://yoursite.com/endpoint",
  "video_endpoint_extras": null,
  "video_set_public": true,
  "token": "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789",
  "uploadIframe": "<iframe src='https://app.vidgrid.com/embed/api/uploader/ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789'></iframe>",
  "uploadIframeBasic": "<iframe src='https://app.vidgrid.com/embed/api/uploader/ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789?uploaderType=basic></iframe>",
  "expires": 1527729792
}

expires is a UNIX Timestamp (UTC) indicating when the temporary token will expire

This endpoint returns a one-time upload token, ways to display an upload form, and some additional data you can see in the sample response to the right.

HTTP Request

POST https://api.vidgrid.com/v1/token/upload

Parameters

api_key string	A User or Organization API key from your VidGrid account.
service_name optional string	The name of your service. Mostly used for informational purposes.
video_endpoint optional string	The Webook URL endpoint where a POST will be made after a video has been uploaded.
video_endpoint_trigger optional string	Determines when to trigger the Webook. The default is ON_UPLOAD_COMPLETE which happens as soon as a video has been uploaded to VidGrid. The other option is ON_PROCESSING_COMPLETE which happens when a video has completed processing and is watchable on VidGrid.
video_endpoint_extras optional array	An array of extra data that will be sent to the Webook endpoint.
video_set_public optional boolean	When set to true, an uploaded video will be viewable by anyone with a link. If set to false, a user must be logged in to your VidGrid account to view the video. If not set, your user or organization defaults will be used.
collection optional string	Automatically add the uploaded video to a folder. Note: Collections are now called Folders in app.

Video API

The Video API allows you to retrieve information about your videos on VidGrid.

Get Video Metadata

Example Request

curl -X POST \
  'https://api.vidgrid.com/v1/video/metadata' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key" : "{key}",
    "randtag" : "123456ABCDEF"
  }'

require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v1/video/metadata")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = '{
  api_key: "{key}",
  randtag : "123456ABCDEF"
}'

response = http.request(request)
puts response.read_body

import requests

url = "https://api.vidgrid.com/v1/video/metadata"

payload = {
  'api_key': "{key}",
  'randtag' : "123456ABCDEF"
}

headers = {
  'Content-Type': "application/json",
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

var settings = {
  "url": "https://api.vidgrid.com/v1/video/metadata",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
  },
  "data": {
    api_key: "{key}",
    randtag : "123456ABCDEF"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Example Response

{
  "message": "",
  "level": "success",
  "data": {
    "title": "This is my video title",
    "hours": "00",
    "mins": "15",
    "secs": "10",
    "ms": "380",
    "totalMs": 910380,
    "videoSignedUrl": "https://www.signed-url-i-can-use-to-download-my-video.com",
    "thumbnailSignedUrl": "https://www.signed-url-i-can-use-to-view-my-video-thumbnail.com",
    "thumbnailSmallSignedUrl": "https://www.signed-url-i-can-use-to-view-my-small-video-thumbnail.com"
  }
}

This endpoint returns metadata for a specified video.

HTTP Request

POST https://api.vidgrid.com/v1/video/metadata

Parameters

api_key string	A User or Organization API key from your VidGrid account.
randtag string	The unique ID of your video.

Get Video File

Example Request

curl -X POST \
  'https://api.vidgrid.com/v1/video/file' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key" : "{key}",
    "randtag" : "123456ABCDEF"
  }'

require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v1/video/file")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = '{
  api_key: "{key}",
  randtag : "123456ABCDEF"
}'

response = http.request(request)
puts response.read_body

import requests

url = "https://api.vidgrid.com/v1/video/file"

payload = {
  'api_key': "{key}",
  'randtag' : "123456ABCDEF"
}

headers = {
  'Content-Type': "application/json",
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

var settings = {
  "url": "https://api.vidgrid.com/v1/video/file",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
  },
  "data": {
    api_key: "{key}",
    randtag : "123456ABCDEF"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Example Response

{
  "message": "",
  "level": "success",
  "data": {
      "signedUrl": "https://www.signed-url-i-can-use-to-download-my-video.com"
  }
}

This endpoint returns a signed url for the video file.

HTTP Request

POST https://api.vidgrid.com/v1/video/file

Parameters

api_key string	A User or Organization API key from your VidGrid account.
randtag string	The unique ID of your video.

Webhooks

The incoming webhook response body will look like this:

{
  "token": "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789",
  "randtag": "123456ABCDEF",
  "videoURL": "https://app.vidgrid.com/view/123456ABCDEF",
  "embedURL": "https://app.vidgrid.com/embed/123456ABCDEF",
  "iframe": "<iframe src='https://app.vidgrid.com/embed/123456ABCDEF'></iframe>",
  "video_endpoint_extras": {
    "extra1": "Something I wanted at my endpoint",
    "extra2": "Another thing I wanted at my endpoint",
  }
}

Since video recording and uploading is an asynchronous task, you can give us a webook URL that we will post to once a video is ready on VidGrid.

You can set the webhook options (video_endpoint, video_endpoint_trigger, and video_endpoint_extras) in both the Recording API and Uploading API.

You can view logs for calls to your endpoint under integration settings in your VidGrid account.

Webhook Response Body

token string	Token that the video was used to record or upload the video.
randtag string	The unique ID for your video.
videoURL string	URL to view your video.
embedURL string	URL you can use as the source of an iframe.
iframe string	An iframe containing the video.
video_endpoint_extras array or null	Any video_endpoint_extras sent through the Recording API or Uploading API.

OpenSearch

OpenSearch is a collection of technologies that allow publishing of search results in a format suitable for syndication and aggregation. It is a way for websites and search engines to publish search results in a standard and accessible format.

Searching Videos

Example Request

curl -X GET \
  'https://api.vidgrid.com/opensearch/?q=testing&api_key={key}'

require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/opensearch/?q=testing&api_key={key}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

import requests

url = "https://api.vidgrid.com/opensearch/"

querystring = {"q":"example%20search","api_key":"{key}"}

headers = {}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

var settings = {
  "url": "https://api.vidgrid.com/opensearch/?q=testing&api_key={key}",
  "method": "GET"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

This endpoint returns a list of video items from VidGrid.

HTTP Request

GET https://api.vidgrid.com/opensearch

Parameters

q string	Your search query.
api_key string	An Organization API key from your VidGrid account.
ptilos optional boolean	Whether or not to prefix returned video titles with VidGrid:

Please visit the OpenSearch Documentation for more options and examples.

Office365 SharePoint

Here is a short demo of how to use OpenSearch in Office365 SharePoint.