Timelines API

Timelines provide a way for users to mark segments of your video into specific tags. To enable timelines, add the following HTML code on your page where you want the timelines to appear:

<!-- timelines will appear here -->
<div class="vidprep_timelines" data-video_id="OOOOOOOO"></div>

Please make sure to use the correct video ID as the value for the data-video_id attribute.


Creating timelines

To create a timeline send a POST request to http://localhost:3999/timelines.

Valid parameters for creating a timeline are:

  • api_key (string) - Your API key (required)
  • group_id (string) - If specified, the timelines will only be available for this group
  • hotkey (string) - Keyboard hotkey for the timeline (not case-sensitive)
  • lag_time (integer) - Milliseconds to add to a tag after it is created
  • lead_time (integer) - Milliseconds to add to a tag before it is created
  • name (string) - Name of the timeline (required)
  • one_click (boolean) - Whether or not tags can be created with a single press of the hotkey (default false)
  • timeline_type (string) - Specifies the type of timeline; valid types are group or user (default user)
  • user_id (string) - If specified, the timelines will only be available for this user
  • video_id (string) - ID of the associated video (required)

Timelines are unique across groups and users.


Example POST to create a new timeline:

POST "http://localhost:3999/timelines"
     api_key="XXXXXXXXXXXXXXXX"
     hotkey="d"
     name="Defense"
     video_id="OOOOOOOO"

Example JSON response:

{
  "created_at":"2012-12-20T20:38:39Z",
  "foreign_group_id":null,
  "foreign_user_id":null,
  "hotkey":"d",
  "id":128,
  "lag_time":0,
  "lead_time":0,
  "name":"Defense",
  "one_click":false,
  "video_id":1075,
  "tags":[],
  "timeline_type":"group"
}

Response data is similar to the POST data, with the addition of:

  • created_at (datetime) - Created date and time for the timeline
  • id (integer) - ID of the newly created timeline
  • tags (object) - Array of tags that exist within this timeline, will be blank for a newly created timeline
  • timeline_type (string) - Specifies the type of timeline, either group or user

Also, please note that group_id and user_id have different names than the POST parameters.
In the response, these fields have foreign_ prepended to them.


Updating timelines

To update a timeline send a PUT request to http://localhost:3999/timelines/TIMELINE_ID.

Input parameters and the response JSON are identical to creating a timeline.


Deleting timelines

You can permanently remove timelines by submitting a REST http delete request to http://localhost:3999/timelines/TIMELINE_ID with the following parameters:

  • api_key (string) - Your API key (required)
  • group_id (string) - ID of the associated group
  • user_id (string) - ID of the associated user
  • video_id (string) - ID of the associated video (required)