COVERITLIVE API (V. 2.0)

Purpose

The CoveritLive API allows users to interact with their CoveritLive (CiL) events. This includes functionality such as retrieving event lists, retrieving data from specific events, publishing content directly into an event, and submitting comments for moderation.

Basic Developer Information

• The API is entirely HTTP-based
  • Methods to retrieve data from the CoveritLive API require a GET request. Methods that submit, change, or destroy data require a POST. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct method. REST principles were used to guide the design.
• API Endpoint
  • For this version the API endpoint where requests should be sent to is:

    https://api.coveritlive.com/remote/2
    

  • The general structure for all requests is:

    https://api.coveritlive.com/remote/{version}/{type}/{action}
    

• Parameters must conform
  • Parameter values should be converted to UTF-8 encoded.

Methods

Comment Management Methods

• comment/create
  • This method adds external comments to events, including the commentor's name and the optional inclusion of the commentor's avatar.
  • Comments are not inserted directly into the event stream, rather they are placed into the comment stream in the Writer's Console, requiring approval/moderation prior to being published.
  • By default submitted comments will be styled to appear exactly like a CiL Reader comment. No custom styling is available.
• comment/list
  • This method provides a list of comments submitted to a CoveritLive event.
  • Includes all comments (published and unpublished).
  • Includes comments from all sources, including those submitted by email or through the API.
• comment/publish
  • This method allows a comment that has been submitted to an event to be published.
  • Comments from any source can be published, including regular comments submitted through the viewer window, comments submitted through the API and by email.

Content Management Methods

• content/create
  • This method allows publishing of content directly into an event, including optional inclusion of the content creators name and avatar.
  • Content is inserted directly into the event stream, and will NOT require approval/moderation prior to being published.
  • By default auto-published text content will be styled to appear exactly like a CiL Writer comment. Custom styling can be included with HTML styling and/or images.
• content/delete
  • This method allows you to delete any item in a live event.
  • Similar to the Live Edit functionality available through the console
  • Any item deletion made will immediately propagate to all readers of the live event in real time.
• content/update
  • This method allows you to update any item in a live event.
  • Similar to the Live Edit functionality available through the console
  • Any update made will immediately propagate to all readers of the live event in real time.

Event Management Methods

• event/create
  • This method allows a user to create a CoveritLive event on the fly. The method returns the event code, so events can be created and populated automatically.
• event/data
  • This method allows a user to retrieve data items from a particular CoveritLive event. This includes text and media published in the event and submitted user comments.
• event/end
  • This method allows a user to end a CoveritLive event. The event must already have been started.
• event/list
  • This method allows a user to retrieve a listing of events which they have access to. These include the users' own events, as well as events from any Enterprise Accounts or Groups that the user is a member of.
• event/start
  • This method allows a user to start a pending/upcoming CoveritLive event. The event must already have been created.
• event/stats
  • This method allows a user to retrieve reader statistics for a CoveritLive Event.
  • Available stats include total page views, total clicks, average duration, and detailed click and page view numbers by day.

Pin Content Management Methods

• pin/create
  • This method allows for the creation of pin items. The pin item id is returned by this method if the pin item is successfully created, allowing for further interactions through the API.
• pin/delete
  • This method allows you to delete any pin item. Any item deletion made will immediately propagate to all readers of the live event in real time.
• pin/list
  • This method provides a list of pin items for a particular event. Both published and unpublished pin items can be retrieved.
• pin/order
  • This method allows the display of published pin items to be ordered. The ordering is achieved by passing a json encoded array of the ids and positions of each pin item.
• pin/update
  • This method allows the content and published status of a pin item to be updated. The only pin items that can be updated are host comments, guest comments, captions in images and any pin items created through the API.

Reply Management Methods

• reply/create
  • This method allows for the creation of replies. The reply id is returned by this method if the reply is successfully created, allowing for further interactions through the API.
• reply/delete
  • This method allows you to delete any reply. Any reply deletion made will immediately propagate to all readers of the live event in real time.
• reply/update
  • This method allows the content of a reply to be updated. Any updates made will immediately propagate to all readers of the live event in real time.

Newsflash Management Methods

• newsflash/create
  • This method allows users to create newsflashes on the fly. The newsflash id is returned by the method if the newsflash is successfully created, allowing for further interactions through the API.
• newsflash/delete
  • This method allows for a newsflash to be deleted. Deleted newsflashes will be removed from all consoles and viewer windows.
• newsflash/list
  • This method returns a list of newsflashes for a particular event. All newsflashes are returned (including those that have been deleted) and all relevant data for each newsflash is returned.
• newsflash/update
  • This method allows users to update currently existing newsflashes. The headline and body text of the newsflash can be updated.

Poll Management Methods

• poll/create
  • This method allows users to create polls on the fly. The poll id is returned by the method if the poll is successfully created, allowing for further interactions through the API.
• poll/end
  • This method allows for a poll to be ended. Ended polls will be removed from viewer window rotation, voting on ended polls will be closed and the final poll results will be added as a new event entry.
• poll/list
  • This method returns a list of polls for a particular event. All polls are returned (including those that have been closed or unpublished) and all relevant data for each poll is returned.
• poll/update
  • This method allows users to update currently existing polls. The only facet of the poll that can be updated is its visibility (whether it is showing or hidden). The text of the poll (question and answers) cannot be updated, to avoid discrepancies in poll results if users vote prior to the poll being updated.

Scoreboard Management Methods

• scoreboard/create
  • This method allows users to create scoreboards on the fly. The scoreboard id is returned by the method if the scoreboard is successfully created, allowing for further interactions through the API.
• scoreboard/delete
  • This method allows for a scoreboard to be deleted. Deleted scoreboards will be removed from all consoles and viewer windows.
• scoreboard/list
  • This method returns a list of scoreboards for a particular event. Only Manual scoreboards are returned (data from Live scoreboards will not be returned) and all relevant data for each scoreboard is returned.
• scoreboard/update
  • This method allows users to update currently existing scoreboards. All text elements of the scoreboard can be updated.

Miscellaneous Methods

• template/list
  • This method returns a list of the templates that are available to the user. The template ids returned can then be used to set the event template in the event/create method.

Request Parameters

Every request may contain the following parameters:

Response Fields

Note that the response will be in JSON format.

Error Responses

A variety of common error responses and instructions on how to rectify them:

Code Samples

PHP Integration Example

Sample Notes:
Specifically for Wordpress but can be used with any commenting system with minor modifications.

• To integrate with wordpress (2+) add the code below to the file wp-comments-post.php after this line that contains: $comment_content = ( isset($_POST['comment']) ) ? trim($_POST['comment']) : null;
• assumes PHP CURL is installed on your server
• assumes you have WP version 2+

// ############################################ 
// Comment into CoverItLive 
// ############################################
	
// ############################################ 
// Values that change per event 
// ############################################ 
// Replace this with your API Access token
$_POST['token']= 'your_auth_token'; 
// Replace this with your event code
$_POST['event_code']= 'your_event_code'; 

// ############################################ 
// Comments from Wordpress site visitor 
// ############################################ 
$_POST['guest_name'] = $comment_author; 
$_POST['tag'] = $comment_author_email;
// If you have an avatar image URL for your users, you can uncomment this code and put the user's avatar URL here.
// $_POST['avatar_uri'] = '';  
$_POST['comment'] = $comment_content;
	
// ############################################ 
// Fixed values for version 2 of the API 
// ############################################ 
$endPointURL = 'https://api.coveritlive.com/remote/2/comment/create'; 
$_POST['format']= 'JSON';
	
// ############################################ 
// User PHP CURL (can be done without CURL on server 
// by using http://ca.php.net/manual/en/function.fopen.php 
// ############################################ 
$content = http_build_query($_POST);

// Use curl to post to your blog. 
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, $endPointURL); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 
curl_setopt($ch, CURLOPT_TIMEOUT, 4); 
curl_setopt($ch, CURLOPT_HTTPHEADER, array()); 
curl_setopt($ch, CURLOPT_POSTFIELDS, $content);

$data = curl_exec($ch);
if (curl_errno($ch)) {
	print curl_error($ch); 
} else {
	curl_close($ch); 
}