Tags API

Tags are used to mark segments of video on a timeline.


Creating tags

To create a tag send a POST request to http://localhost:3999/tags.

Valid parameters for creating a tag are:

  • api_key (string) - Your API key (required)
  • group_id (string) - The ID of the current user group
  • end_time (integer) - The ending time for the tag, in milliseconds (required)
  • start_time (integer) - The starting time for the tag, in milliseconds (required)
  • timeline_id (integer) - The timeline that this tag belongs to (required)
  • user_id (string) - The ID of the current user

Example POST to create a new tag:

POST "http://localhost:3999/tags"
     api_key="XXXXXXXXXXXXXXXX"
     end_time=7400
     start_time=5000
     timeline_id=83

This will create a tag on timeline #83 with a start time of 5.0 seconds and an end time of 7.4 seconds.

Example JSON response:

{
  "created_at":"2012-12-21T22:19:10Z",
  "description":null,
  "end_time":7400,
  "foreign_group_id":null,
  "foreign_user_id":null,
  "id":201,
  "model_class":"Timeline",
  "model_id":83,
  "name":"Goals",
  "start_time":5000
}

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

  • created_at (datetime) - Created date and time for the tag
  • description (string) - Not used via the API
  • model_id (integer) - ID of the newly created tag
  • model_class (string) - Should always be "Timeline"
  • name (string) - Name of the timeline

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.


Deleting tags

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

  • api_key (string) - Your API key (required)
  • timeline_id (string) - ID of the associated timeline (required)