Navbar
Version
Shell Ruby Python JavaScript

API Reference

Welcome to the VidGrid REST API!

You can use this API to create and manage resources on your VidGrid account. The API is meant to be used server-side and all requests should be made over SSL.

Code examples can be viewed in the area to the right, and you can switch the language of the examples with the tabs in the top right.

Help, Support, & Feedback

If you have feedback or feature requests, please send us your feedback or request.

If you discover a mistake in the documentation, please report an issue.

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

Authentication

Example request using HTTP basic auth.

# HTTP Basic Auth
curl 'https://api.vidgrid.com/v2/videos/identifier' \
  -H 'Content-Type: application/json' \
  -u {key}:{secret}

# Using a Basic token in an Authorization header
curl 'https://api.vidgrid.com/v2/videos/identifier' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/videos/identifier")

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

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'

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

url = "https://api.vidgrid.com/v2/videos/identifier"

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

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.vidgrid.com/v2/videos/identifier',
  headers: {
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Authentication is done via HTTP Basic Auth using an API key and secret as a username and password.

To use HTTP Basic Auth, generate a token by base64 encoding {key}:{secret} and pass it in an Authorization header.

Important: Your API key and secret give full permissions to manage content on your VidGrid account through the API. They should NEVER be exposed client side.

API Keys

All API requests are made using an API key on behalf of a user in your VidGrid account.

You can find your API keys under your VidGrid integration settings and roll new ones if desired.

Responses

Our API returns JSON responses with standard HTTP status codes.

You can see examples of successful and failed responses as well as different HTTP status codes we may return below.

Success Responses

Example success response with a data object.

{
  "data": {
    ...
  }
}

Example success response with a data array.

{
  "data": [{
    ...
  }, {
    ...
  }]
}

All successful GET responses will return a data array while all other success responses will return a data object.

HTTP Status Codes

Code Title Description
200 OK The request was successfull.
204 No Content The server has successfully fulfilled the request and there is no additional content to send in the response.

Error Responses

Example error response.

{
  "message": "A message explaining what went wrong."
}

All of our error responses will return a message describing what went wrong.

HTTP Status Codes

Code Title Description
401 Unauthorized The request lacks valid authentication credentials.
403 Forbidden The user is not authorized to interact with the resource in this way.
404 Not found The resource does not exist.
422 Validation error A validation error occurred.
50X Internal Server Error An error occurred with our API.

Throttling

We implement rate-limiting so as to not overwhelm our API. By default this is set to 60 request per minute.

You can see your current limit and remaining requests by reading the X-RateLimit-Limit and X-RateLimit-Remaining headers returned in every response.

To request a higher limit, please contact us.

Video Creation Token API

The Video Creation Token API allows you to request a token that can be used to record or upload videos into your VidGrid account.

See Example Usage for more information.

Token Resources

Record Token Resource

Example create record token response.

{
  "data": {
    "token": "...",
    "expires": 1563328704,
    "recorder": {
      "download_url": "...",
      "launch_uri": "...",
      "iframe_button": "..."
    }
  }
}

The Record Token Resource returned in a successful response.

Prop Type Value
token string One-time token that is used for authentication when recording and uploading a video.
expires Timestamp UNIX Timestamp (UTC) indicating when the temporary token will expire.
recorder.download_url string URL that can be used to download the recorder.
recorder.launch_uri string URI that can be used to launch the recorder.
recorder.iframe_button string Iframe containing a record button. It will handle downloading and launching the recorder.

Upload Token Resource

Example create upload token response.

{
  "data": {
    "token": "...",
    "expires": 1563328704,
    "uploader": {
      "iframe": "...",
      "iframe_basic": "..."
    }
  }
}

The Upload Token Resource returned in a successful response.

Prop Type Value
token string One-time token that is used for authentication when uploading a video.
expires Timestamp UNIX Timestamp (UTC) indicating when the temporary token will expire.
uploader.iframe string Iframe containing a simple upload dropzone.
recorder.iframe_basic string Iframe containing a simple upload button.

Direct Upload Token Resource

Example create direct upload token response.

{
  "data": {
    "formAttributes": {
        "action": "...",
        "method": "...",
        "enctype": "..."
    },
    "formInputs": {
        "key": "... ${filename}",
        "acl": "...",
        "x-amz-server-side-encryption": "...",
        "X-Amz-Credential": "...",
        "X-Amz-Algorithm": "...",
        "X-Amz-Date": "...",
        "Policy": "...",
        "X-Amz-Signature": "..."
    },
    "fileParamName": "...",
    "cloudUploadCallbackUrl": "...",
    "token": "..."
  }
}

The Direct Upload Token Resource returned in a successful response.

See Direct Upload Example for more information on implementing this method.

Prop Type Value
formAttributes array Form attributes necessary for the S3 upload.
formInputs array Key/value pairs necessary for the S3 upload.
Important: formInputs.key contains a ${filename} string that needs to be replaced with a unique file name for each file uploaded. This will also be used for the video title in VidGrid unless video.title is set in the Create Token request.
fileParamName string The required key name that should contain the file data for uploading.
Important: Amazon requires this to be the last key/value pair included in the POST to S3.
e.g. <input type="file" name="{fileParamName}">
cloudUploadCallbackUrl string URL to POST to once a video has finished uploading to S3 and is ready for processing. Returns a video identifier.
Important: you need to include cloudKey with the request which is the value of formInputs.key after ${filename} has been replaced.
token string One-time token that is used for authentication when uploading a video. It is then mainly used for informational purposes.

Create Token

This endpoint generates and returns a Token Resource that can be used for creating videos.

HTTP Request

Example create record token request.

curl -X POST \
  'https://api.vidgrid.com/v2/tokens' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic {token}' \
  -d '{
    "type": "record",
    "video": {
        "title": "My New Video",
        "public": false
    },
    "recorder": {
        "auto_close_recorder": true,
        "hide_video_title_input": true,
        "on_install": {
            "auto_authenticate": true,
            "show_instructions_page": true
        }
    },
    "webhook_extras": {
      "key1": "val1",
      "key2": "val2"
    }
  }'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/tokens")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'
request.body = '{
  "type": "record",
  "video": {
    "title": "My New Video",
    "public": false
  },
  "recorder": {
    "auto_close_recorder": true,
    "hide_video_title_input": true,
    "on_install": {
      "auto_authenticate": true,
      "show_instructions_page": true
    }
  },
  "webhook_extras": {
    "key1": "val1",
    "key2": "val2"
  }
}'

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

url = "https://api.vidgrid.com/v2/tokens"

payload = {
  "type": "record",
  "video": {
    "title": "My New Video",
    "public": false
  },
  "recorder": {
    "auto_close_recorder": true,
    "hide_video_title_input": true,
    "on_install": {
      "auto_authenticate": true,
      "show_instructions_page": true
    }
  },
  "webhook_extras": {
    "key1": "val1",
    "key2": "val2"
  }
}
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.vidgrid.com/v2/tokens',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  body: {
    type: "record",
    video: {
        title: "My New Video",
        public: false
    },
    recorder: {
        auto_close_recorder: true,
        hide_video_title_input: true,
        on_install: {
            auto_authenticate: true,
            show_instructions_page: true
        }
    },
    webhook_extras: {
      key1: "val1",
      key2: "val2"
    }
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

POST https://api.vidgrid.com/v2/tokens

HTTP Parameters

Param Type Description Default
type string The type of token that will be used. See Token Types for more info.
Possible values: record, upload, direct_upload.
Required
video Video Params Object Sets properties on videos created with this token. -
recorder Recorder Params Object Configures recorder behavior when launched with this token.
Only applies to tokens with a type of record.
-
webhook_extras array Any extra data that you would like to be sent along when Webhook events are fired. -

Video Params Object

Sets properties on videos created with a specific token.

Param Type Description Default
title string Sets the title for the created video.
If recorder.hide_video_title is set to false the end user will have the option to set their own title from within the recorder.
-
public 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 default settings will be used. -
folder string Automatically add uploaded videos to a folder. This should be set to a folder identifier. -

Recorder Params Object

Configures recorder behavior when launched via a specific token.

Only applies to tokens with a type of record.

Param Type Description Default
auto_show_video_page boolean Whether or not to automatically open the video in the user's browser after recording. false
auto_close_recorder 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. false
hide_video_title_input boolean Whether or not to allow the user to title the video after recording. false
default_fullscreen boolean Whether or not the recorder should launch in fullscreen mode. false
force_webcam_only boolean Whether or not the recorder should be restricted to webcam only mode. false
on_install.auto_authenticate 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. true
on_install.show_instructions_page 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. false

Example Usage

Below are some examples of how you can implement the video creation API.

Recording Example

Use a record token to allow users to record new videos with the VidGrid Screen Recorder and upload them to your VidGrid account.

  1. Request a record token from VidGrid and save the returned data.
  2. Display a record button to the user using the either recorder.iframe_button or recorder.launch_uri (we recommend using the iframe since it will handle downloading and installing the recorder for first time users).
  3. Create a Webook and subscribe to a Video Uploaded or Video Ready event. Once a user has created a video, the event will fire and a Video Resource will be sent to the webhook endpoint. You can then use the resource as you wish (e.g. embed the video somewhere within your app).

Uploading Example

Use an upload token to allow users to upload pre-existing videos to VidGrid using a web uploader.

  1. Request an upload token from VidGrid and save the returned data.
  2. Display an uploader using the uploader.iframe or uploader.iframe_basic.
  3. Create a Webook and subscribe to a Video Uploaded or Video Ready event. Once a user has uploaded a video, the event will fire and a Video Resource will be sent to the webhook endpoint. You can then use the resource as you wish (e.g. embed the video somewhere within your app).

Direct Upload Example

A direct_upload token is used to bypass the VidGrid web uploader and upload videos directly to Amazon S3. It is a little more complex to implement but provides greater flexibility than the normal upload token.

  1. Request a direct_upload token from VidGrid and save the returned data.
  2. Make a POST request to S3 using the formAttributes, formInputs, and file data with the fileParamName as its key.
    Important: Amazon requires the file data to be the last key/value pair included in the POST to S3.
  3. Once the upload is complete, make a POST to cloudUploadCallbackUrl letting VidGrid know the file is ready to be processed.
  4. Wait as the video goes through the normal processing steps. Webhook Events events will fire as they normally would.

Video API

The Video API allows you to interact with videos on your VidGrid account.

Video Resource

The Video Resource(s) returned in a successful response.

Property types with a ? are only returned if they are requested with a Retrieve Video Params Array.

Example Video Resource Object.

{
  "identifier": "...",
  "title": "Video Title",
  "view_url": "https://app.vidgrid.com/view/identifier",
  "embed_url": "https://app.vidgrid.com/embed/identifier",
  "signed_url": "...",
  "metadata": {
    "width": 1280,
    "height": 720,
    "duration": 445.03,
    "filesize": 25109038
  },
  "thumbnail": {
    "signed_url": "...",
    "signed_url_small": "..."
  },
  "jwts": {
    "view": "...",
    "edit": "..."
  },
  "captions": [
    Caption Resource Object,
    Caption Resource Object
  ]
}
Prop Type Value
identifier string The unique identifier for the video.
title string Title of the video.
view_url string URL to view the video.
embed_url string URL to embed the video.
signed_url ?string Signed URL that can be used to view the video file directly.
Expires after 6 hours.
metadata.duration ?number Duration of the video in seconds.
metadata.width ?number Width of the video.
Width may differ between videos uploaded and videos done processing.
metadata.height ?number Height of the video.
Height may differ between videos uploaded and videos done processing.
metadata.filesize ?number Size of the video in bytes.
Filesize may differ between videos uploaded and videos done processing.
thumbnail.signed_url ?string Signed URL for the video thumbnail.
thumbnail.signed_url_small ?string Signed URL for a smaller version of the video thumbnail.
jwt.view ?string A single-use access token that can be used to grant view permissions for a video on VidGrid. On page load a new access token will be generated that allows the user to view the video for 6 hours, but the token in the URL will have expired.
You can use the token with view or embed URLs as follows: {embed_url}?auth={jwts.view}
jwt.edit ?string A single-use access token that can be used to grant edit permissions for a video on VidGrid. On page load a new access token will be generated that allows the user to edit the video for 6 hours, but the token in the URL will have expired.
You can use the token with view or embed URLs as follows: {embed_url}?auth={jwts.edit}
captions ?array An array of Caption Resources attached to this video.

Create Video

To create videos you will need to make use of the Video Creation Token Api.

Retrieve Video

This endpoint returns an array of Video Resources.

HTTP Request

Example retrieve video request.

curl -X GET \
  'https://api.vidgrid.com/v2/videos' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "identifiers": [
      "...",
      "..."
    ],
    "include": [
      "signed_url",
      "metadata",
      "thumbnail",
      "jwts",
      "captions"
    ]
  }'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/videos")

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

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'
request.body = '{
  "identifiers": [
    "...",
    "..."
  ],
  "include": [
    "signed_url",
    "metadata",
    "thumbnail",
    "jwts"
  ]
}'

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

url = "https://api.vidgrid.com/v2/videos"

payload = '{
  "identifiers": [
    "...",
    "..."
  ],
  "include": [
    "signed_url",
    "metadata",
    "thumbnail",
    "jwts"
  ]
}'
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.vidgrid.com/v2/videos',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  body: { 
    identifiers: [
      '...',
      '...'
    ],
    include: [ 
      'signed_url', 
      'metadata', 
      'thumbnail',
      'jwts'
    ] 
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example retrieve video response. See Video Resource for more details.

{
  "data": [
    Video Resource Object,
    Video Resource Object
  ]
}

GET https://api.vidgrid.com/v2/videos

HTTP Parameters

Param Type Description Default
identifier string The unique identifier of a video.
You may pass this in the body or on the URL: /v2/videos/identifier
Required unless identifiers is set
identifiers array The unique identifiers of the desired videos. When set, this takes priority over identifier. -
include Retrieve Video Params Array An array of properties to be included with the returned Video Resources. -

Retrieve Video Params Array

An array of properties to be included with a returned Video Resource.

Param Description
signed_url Request a signed URL that can be used to view the video file directly.
metadata Request metadata about the video.
thumbnail Request signed URLs that can be used to view video thumbnails.
jwts Request JWT tokens that can be used to view and/or edit a video on VidGrid.
captions Request all of the Caption Resources attached to this video.

Update Video

This endpoint updates a video and then returns it as a Video Resource.

HTTP Request

Example update video request.

curl -X PATCH \
  'https://api.vidgrid.com/v2/videos/identifier' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "properties": [
      "title": "Updated Video Title"
    ]
  }'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/videos/identifier")

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

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'
request.body = '{
  "properties": [
    "title": "Updated Video Title"
  ]
}'

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

url = "https://api.vidgrid.com/v2/videos/identifier"

payload = '{
  "properties": [
    "title": "Updated Video Title"
  ]
}'
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'PATCH',
  url: 'https://api.vidgrid.com/v2/videos/identifier',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  body: { 
    properties: [
      title: "Updated Video Title"
    ]
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example update video response. See Video Resource for more details.

{
  "data": Video Resource Object
}

PATCH https://api.vidgrid.com/v2/videos

HTTP Parameters

Param Type Description Default
identifier string The unique identifier of a video.
You may pass this in the body or on the URL: /v2/videos/identifier
Required
properties Update Video Props Object An object used to update properties on a video. Required

Update Video Props Object

An object used to update properties on a video.

Param Type Description
title string Updates the video title.

Delete Video

This endpoint deletes a video.

HTTP Request

Example delete video request.

curl -X DELETE \
  'https://api.vidgrid.com/v2/videos/identifier' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "trash": true
  }'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/videos/identifier")

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

request = Net::HTTP::Delete.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'
request.body = '{
  "trash": true
}'

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

url = "https://api.vidgrid.com/v2/videos/identifier"

payload = '{
  "trash": true
}'
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'DELETE',
  url: 'https://api.vidgrid.com/v2/videos/identifier',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  body: { 
    trash: true
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The delete video endpoint returns a 204 No Content response when successful.

DELETE https://api.vidgrid.com/v2/videos

HTTP Parameters

Param Type Description Default
identifier string The unique identifier of a video.
You may pass this in the body or on the URL: /v2/videos/identifier
Required
trash bool If set to true, the video will be placed in the VidGrid trash for 30 days. If set to false, the trash will be skipped and the video will be deleted immediately. true

Caption API

The Caption API allows you to request and manage closed captioning on your Videos.

Caption Resource

The Caption Resource(s) returned in a successful response.

Example Caption Resource Object.

{
  "identifier": "...",
  "type": "...",
  "status": "...",
  "language": "..."
}
Prop Type Value
identifier string The unique identifier for the caption on VidGrid.
type string The type of caption resource.
Possible values: machine,professional,manual
status string The current status of this caption resource.
Possible values: QUEUED,PENDING,IN_PROGRESS,CANCELED,FAILED,COMPLETED
language ?string The language of the caption file.

Create Caption

This endpoint makes a caption request for a Video Resource. It returns a Caption Resource with a status but the caption will not be ready immediately.

HTTP Request

Example create caption request.

curl -X POST \
  'https://api.vidgrid.com/v2/captions' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_identifier": "...",
    "type": "machine"
  }'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/captions")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'
request.body = '{
  "video_identifier": "...",
  "type": "machine"
}'

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

url = "https://api.vidgrid.com/v2/captions"

payload = '{
  "video_identifier": "...",
  "type": "machine"
}'
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.vidgrid.com/v2/captions',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  body: { 
    video_identifier: "...",
    type: "machine"
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example create caption response. See Caption Resource for more details.

{
  "data": Caption Resource Object
}

POST https://api.vidgrid.com/v2/captions

HTTP Parameters

Param Type Description Default
video_identifier string The unique identifier of the video you are requesting a caption for. Required
type string The type of caption you would like to request.
Possible values: machine, professional
Required

Retrieve Caption

This endpoint returns an array of Caption Resources.

HTTP Request

Example retrieve caption request.

curl -X GET \
  'https://api.vidgrid.com/v2/captions' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "identifiers": [
      "...",
      "..."
    ]
  }'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/captions")

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

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'
request.body = '{
  "identifiers": [
    "...",
    "..."
  ]
}'

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

url = "https://api.vidgrid.com/v2/captions"

payload = '{
  "identifiers": [
    "...",
    "..."
  ]
}'
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.vidgrid.com/v2/captions',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  body: { 
    identifiers: [
      '...',
      '...'
    ]
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example retrieve caption response. See Caption Resource for more details.

{
  "data": [
    Caption Resource Object,
    Caption Resource Object
  ]
}

GET https://api.vidgrid.com/v2/captions

HTTP Parameters

Param Type Description Default
identifier string The unique identifier of a caption.
You may pass this in the body or on the URL: /v2/captions/identifier
Required unless identifiers is set
identifiers array The unique identifiers of the desired captions. When set, this takes priority over identifier. -

Delete Caption

This endpoint deletes a caption.

HTTP Request

Example delete caption request.

curl -X DELETE \
  'https://api.vidgrid.com/v2/captions/identifier' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/captions/identifier")

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

request = Net::HTTP::Delete.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'

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

url = "https://api.vidgrid.com/v2/captions/identifier"

payload = ''
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'DELETE',
  url: 'https://api.vidgrid.com/v2/captions/identifier',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The delete caption endpoint returns a 204 No Content response when successful.

DELETE https://api.vidgrid.com/v2/captions

HTTP Parameters

Param Type Description Default
identifier string The unique identifier of a caption.
You may pass this in the body or on the URL: /v2/captions/identifier
Required

Folder API

The Folder API allows you to interact with folders on your VidGrid account.

Folder Resource

The Folder Resource(s) returned in a successful response.

Property types with a ? are only returned if they are requested with a Folder Params Array.

Example Folder Resource Object.

{
  "identifier": "...",
  "title": "Folder Title",
  "is_in_org_library": false,
  "view_url": "https://app.vidgrid.com/content/identifier",
  "playlist": {
    "enabled": false,
    "view_url": "https://app.vidgrid.com/playlist/identifier",
    "embed_url": "https://app.vidgrid.com/playlist/identifier?embedded=1"
  }
}
Prop Type Value
identifier string The unique identifier for the folder.
title string Title of the folder.
view_url string URL to view the folder.
is_in_org_library bool Whether or not this folder is in the Organization Library.
playlist.enabled ?string Whether this folder can be used as a playlist.
playlist.view_url ?string URL to view the playlist for this folder.
playlist.embed_url ?string URL to embed the playlist for this folder.

Create Folder

This endpoint creates a folder and then returns it as a Folder Resource.

HTTP Request

Example create folder request.

curl -X POST \
  'https://api.vidgrid.com/v2/folders' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "New Folder Title",
    "is_in_org_library": false
  }'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/folders")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'
request.body = '{
  "title": "New Folder Title",
  "is_in_org_library": false
}'

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

url = "https://api.vidgrid.com/v2/folders"

payload = '{
  "title": "New Folder Title",
  "is_in_org_library": false
}'
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.vidgrid.com/v2/folders',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  body: { 
    title: "New Folder Title",
    is_in_org_library: false
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example create folder response. See Folder Resource for more details.

{
  "data": Folder Resource Object
}

POST https://api.vidgrid.com/v2/folders

HTTP Parameters

Param Type Description Default
title string Sets the folder title. Required
is_in_org_library bool Whether or not to place this folder into the Organization Library. false

Retrieve Folder

This endpoint returns an array of Folder Resources.

HTTP Request

Example retrieve folder request.

curl -X GET \
  'https://api.vidgrid.com/v2/folders' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json'
  -d '{
    "identifiers": [
      "...",
      "..."
    ],
    "include": [
        "playlist"
    ]
  }'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/folders")

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

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'
request.body = '{
  "identifiers": [
    "...",
    "..."
  ],
  "include": [
    "playlist"
  ]
}'

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

url = "https://api.vidgrid.com/v2/folders"

payload = '{
  "identifiers": [
    "...",
    "..."
  ],
  "include": [
    "playlist"
  ]
}'
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.vidgrid.com/v2/folders',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  body: { 
    identifiers: [
      '...',
      '...'
    ],
    include: [
      'playlist' 
    ]
  },  
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

GET https://api.vidgrid.com/v2/folders

Example retrieve folder response. See Folder Resource for more details.

{
  "data": [
    Folder Resource Object,
    Folder Resource Object
  ]
}

HTTP Parameters

Param Type Description Default
identifier string The unique identifier of a folder.
You may pass this in the body or on the URL: /v2/folders/identifier
Required unless identifiers is set
identifiers array The unique identifiers of the desired folders. When set, this takes priority over identifier. -
include Folder Params Array An array of properties to be included with the returned Folder Resources. -

Folder Params Array

An array of properties to be included with a returned Folder Resource.

Param Description
playlist Request playlist data for the folder.

Update Folder

This endpoint updates a folder and then returns it as a Folder Resource.

HTTP Request

Example update folder request.

curl -X PATCH \
  'https://api.vidgrid.com/v2/folders/identifier' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "properties": [
        "title": "Updated Folder Title"
    ]
  }'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/folders/identifier")

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

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'
request.body = '{
  "properties": [
      "title": "Updated Folder Title"
  ]
}'

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

url = "https://api.vidgrid.com/v2/folders/identifier"

payload = '{
  "properties": [
      "title": "Updated Folder Title"
  ]
}'
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'PATCH',
  url: 'https://api.vidgrid.com/v2/folders/identifier',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  body: { 
    properties: [
      title: "Updated Folder Title"
    ]
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example update folder response. See Folder Resource for more details.

{
  "data": Folder Resource Object
}

PATCH https://api.vidgrid.com/v2/folders

HTTP Parameters

Param Type Description Default
identifier string The unique identifier of a folder.
You may pass this in the body or on the URL: /v2/folders/identifier
Required
properties Update Folder Props Object An object used to update properties on a folder. Required

Update Folder Props Object

An object used to update properties on a folder.

Param Type Description
title string Updates the folder title.

Delete Folder

This endpoint is used to delete a folder. The contents of the folder (videos and other folders) are not deleted and will still be accessible from your VidGrid account.

HTTP Request

Example delete folder request.

curl -X DELETE \
  'https://api.vidgrid.com/v2/folders/identifier' \
  -H 'Authorization: Basic {token}' \
  -H 'Content-Type: application/json'
require 'uri'
require 'net/http'

url = URI("https://api.vidgrid.com/v2/folders/identifier")

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

request = Net::HTTP::Delete.new(url)
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Basic {token}'

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

url = "https://api.vidgrid.com/v2/folders/identifier"

payload = ''
headers = {
  'Content-Type': "application/json",
  'Authorization': "Basic {token}",
}

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

print(response.text)
// NodeJS

var request = require("request");

var options = {
  method: 'DELETE',
  url: 'https://api.vidgrid.com/v2/folders/identifier',
  headers: { 
    Authorization: 'Basic {token}',
    'Content-Type': 'application/json' 
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The delete folder endpoint returns a 204 No Content response when successful.

DELETE https://api.vidgrid.com/v2/folders

HTTP Parameters

Param Type Description Default
identifier string The unique identifier of a folder.
You may pass this in the body or on the URL: /v2/folders/identifier
Required

Webhooks

You can create webhooks which subscribe to events from the Webhook Settings page in your VidGrid account.

Events

Each webhook created can subscribe to one or more events. When an event is fired, VidGrid will POST data to the endpoint specified in the webhook.

You can view logs for events fired from the Webhook Settings page in your VidGrid account.

Video Uploaded

Example data sent with Video Uploaded event.

{
  "data": {
    "resource": ...,
    "token": "...",
    "extras": {
      "key1": "value 1",
      "key2": "value 2"
    }
  }
}

Fired when a video is uploaded to VidGrid. The video is currently embeddable, but not playable.

Properties of a base Video Resource as well as metadata are available at this point.

Note: Some metadata values could change between video uploading and video processing. See Video Resource for more details.

Prop Type Value
resource Video Resource The video resource tied to this event.
token ?string Token used if this video was created through the API.
extras ?array An array of extra data if sent through the API.

Video Ready

Example data sent with Video Ready event.

{
  "data": {
    "resource": ...,
    "token": "...",
    "extras": {
      "key1": "value 1",
      "key2": "value 2"
    }
  }
}

Fired when a video is processed and ready for playback on VidGrid.

Properties of a base Video Resource as well as signed_url, duration, and jwts are available at this point.

Note: Video thumbnail may not be ready at this point, but embedded videos will be updated automatically when the thumbnail is generated.

Prop Type Value
resource Video Resource The video resource tied to this event.
token ?string Token used if this video was created through the API.
extras ?array An array of extra data if sent through the API.

Logging

You can find a log of all recent API activity on the API Dashboard within VidGrid.

You can find webhook logs on the Webhook Settings page within VidGrid.

Embedding Videos

Embed URLs

Video Resources will contain an embed_url that can be used to embed your video in an iframe.

Iframes

Basic iframe example.

<iframe src="{video.embed_url}" title="{video.title}" 
        width="640" height="360" 
        allowTransparency="true" mozallowfullscreen webkitallowfullscreen allowfullscreen frameBorder="0"
        style="background-color:transparent;">
</iframe>

Responsive iframe example.

<div style="position:relative;overflow:hidden;padding-top:56.25%;">
  <iframe src="{video.embed_url}" title="{video.title}" 
          allowTransparency="true" mozallowfullscreen webkitallowfullscreen allowfullscreen frameBorder="0"
          style="background-color:transparent;position:absolute;top:0;left:0;width:100%;height:100%;">
  </iframe>
</div>

There are two main ways you can embed your video. You can use a basic iframe, or you can use a responsive iframe with a 16:9 aspect ratio. We recommend using a responsive iframe.

You can see our recommended iframe codes in the section to the right.

Tracking Viewers

There may be times when you know who is viewing a VidGrid video, but that user may not have (or is not logged into) a VidGrid account.

If this is the case, you have the option to pass certain tracking data on a video view or embed URL in order to track who is watching a video through VidGrid video analytics.

Example of tracking name and email of a user through a view URL.

https://app.vidgrid.com/view/identifier?vgname={name}&vgemail={email}

Query Parameters

Param Type Description
vgname string The name of a user.
vgemail string The email of a user.

Controlling the Player

Player.js

Player.js is a JavaScript library that allows developers to programmatically control video and audio within an iframe. It can be used with VidGrid embedded videos.

For complete documentation on the capabilities of Player.js, please visit http://playerjs.io.

Installation

Player.js is hosted on Embedly's CDN:

<script type="text/javascript" src="//cdn.embed.ly/player-0.1.0.min.js"></script>

You can also install it via npm:

npm install player.js

Example Usage

# See JavaScript tab as this is a client-side implementation only.
# See JavaScript tab as this is a client-side implementation only.
# See JavaScript tab as this is a client-side implementation only.
const iframe = document.querySelector('iframe');
const player = new playerjs.Player(iframe);

player.on('ready', () => {
  player.play();
});

VidGrid supports auto playing videos when the autoplay query parameter is set to true on the video URL. However, some browsers now block auto playing videos from starting. To get around this, we can use Player.js.

Simply follow the Installation instructions and then follow the code example to the right.

Third-Party Cookies

With certain integrations that utilize embedding VidGrid videos/pages (such as LTI integrations using SSO) you may run into a problem with saving cookies in Safari & iOS.

The problem occurs when a user has "Prevent cross-site tracking" selected under Privacy in Safari (the default option) and is loading content within an iframe. Safari will prevent cookies saved from the host within the iframe unless the user has previously visited that host as the root document and had a cookie saved at that point.

For instance, foo.com has an iframe which contains bar.com. If the user has not visited bar.com outside of an iframe, the bar.com iframe will not be able to save a cookie.

Solution 1 (Dialog)

# See JavaScript tab as this is a client-side solution only.
# See JavaScript tab as this is a client-side solution only.
# See JavaScript tab as this is a client-side solution only.
function openDialog() {
  window.open('https://app.vidgrid.com/cookie/dialog', 'Cookie dialog', 'height=200,width=150');
}

var trigger = document.querySelector(".open-dialog");

trigger.addEventListener("click", openDialog);

This will open a dialog window to app.vidgrid.com, save a cookie, and immediately close the dialog. The user MUST initiate this action (ie. through a button click) so the popup does not get blocked by the browser.

In most cases we have already implemented this solution inside of our iframes as a fallback. However, you may still wish to use it and/or Solution 2 for a different workflow.

Client-Side HTTP Request

GET https://app.vidgrid.com/cookie/dialog

Note that we are using app.vidgrid.com as opposed to api.vidgrid.com

Solution 2 (Redirect)

# See JavaScript tab as this is a client-side solution only.
# See JavaScript tab as this is a client-side solution only.
# See JavaScript tab as this is a client-side solution only.
window.location = "https://app.vidgrid.com/cookie/redirect?url=https%3A%2F%2Fwww.foo.com";

This will visit app.vidgrid.com, save a cookie, and immediately redirect to the desired URL.

Client-Side HTTP Request

GET https://app.vidgrid.com/cookie/redirect

Note that we are using app.vidgrid.com as opposed to api.vidgrid.com

HTTP Parameters

Param Type Description Default
url string URL encoded string for VidGrid to redirect to after saving the cookie. Required

Third Party Integrations

VidGrid has several third party integrations that you can take advantage of.

You can find out more information about our integrations in the VidGrid help center.

LTI

You can find API keys for LTI integrations on your VidGrid integration settings page.

Check our help articles for more information about LTI integrations.

Zoom

You can find API keys for Zoom integrations on your VidGrid integration settings page.

Check our help articles for more information about Zoom integrations.

Email Clients

VidGrid has integrations with email clients such as Gmail, Outlook, and SalesLoft.

Learn more about our email integrations in our help center.