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:

Parameter Description Required
type This specifies the type of request that is to be performed (e.g. comment) - contained in the API endpoint url. yes
action This specifies the action that is to be performed on the type of request (e.g. create) - contained in the API endpoint url. yes
token This is the API Access token that identifies the user/application calling the API. It is used to determine the calling user's access to particular events. A user may only access their own events and any events that are part of Groups or Enterprise Accounts that they belong to. The API Access token is automatically generated when a user account is created, and is available on the APIs page. yes

Response Fields

Note that the response will be in JSON format.

Field Description
result
  • For requests which were successful, the value of this element will be: success.
  • For request which failed, the value of this element will contain an error code.
message
  • For successful requests this will contain the value: true.
  • For failed requests this will contain a short explanation of the error.
type This specifies the type of request (e.g. comment).
action This specifies the requested action (e.g. create).
version The API version that was used to generate the response.
data This field is present in the response for requests that return additional data. For the event/list request, this field contains the listing of events, and for the event/data request, this field contains the event data.

Error Responses

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

result response message response solution
invalid_request_endpoint The requested endpoint was invalid. Required format: /remote/version/type/action Ensure that the url endpoint is in the correct format. If any of version, type or action is missing, this error is triggered.
invalid_request_method various Ensure that the correct HTTP method is used against the endpoint. POSTs are used to add or modify data, GETs are used to retrieve data.
invalid_request_type The type parameter was invalid, currently valid requests are: ... Ensure that the type parameter is present in the request (in the url), and its value is valid.
invalid_request_action The action parameter was invalid, currently valid requests are: ... Ensure that the action parameter is present in the request (in the url), and its value is valid.
invalid_request Invalid request: . Currently valid requests are: ... Ensure that the type/action parameter combination is valid.
missing_token_param The token parameter was missing from the request. Ensure that the token parameter is present in the request. A user's API Access token can be found on the APIs and Event Feeds page.
invalid_token_param The token param supplied was invalid. Ensure the token parameter in the request is correct. The token can be found on the APIs and Event Feeds page.
api_not_enabled APIs have been disabled for your user account. Please contact customer service. API access for your user account has been disabled. Contact customer service for further information.
both_group_and_account_provided Both a group and account code were provided. Only 1 of group/account code should be included in the request parameters.
invalid_code The event code requested is invalid - check the event code used. Ensure the event code is present. If it is, ensure that it is the correct value.
account_api_not_enabled The event you are accessing is part of an Enterprise Account for which APIs have been disabled. Please contact customer service. API access for the Enterprise Account has been disabled. Contact customer service for further information.
event_code_unauthorized You do not have access to the event specified by the event code. The user identified by the token request parameter does not have access to the event specified by the event_code parameter. Ensure the user is part of the necessary Groups and/or Enterprise Account.
server_error Various There was a server error while processing the request. Try again, and if the error persists, contact customer service.
event_not_active The event specified by the event code is not in an active state. The majority of API methods against an event require that event to be active. The only exceptions are read-only requests, and the comment/create requests.
event_not_pending The event specified by the event code is not in a pending state. The event/start API method requires that the specified event be in a pending state.
event_not_completed The event specified by the event code is not in a completed state. The event/stats API method requires that the specified event be in a completed state.
event_not_active_pending The event specified by the event code is not in an active or pending state. The comment/create API method requires that the specified event be in a pending state or active state.

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); 
}

Python Integration Example

Sample Notes:
Pulls a feed of photos from Flickr and auto-publishes them into a CiL Event using the content/create API method


import 	sys, urllib, urllib2, json, time

FLICKR_API_ENDPOINT = "http://api.flickr.com/services/rest/"
FLICKR_SECRET = 'your_flickr_secret'
FLICKR_API_KEY = 'your_flickr_api_key'

CIL_API_ENDPOINT = "https://api.coveritlive.com/remote/2/"
CIL_API_CONTENT_REQUEST = "content/create"
# replace this with your API Access Token
CIL_API_TOKEN = "your_api_access_token"
# replace this with your event code
CIL_EVENT_CODE = "your_event_code"

def convertToJSON(data):	
    respStr = data.replace("jsonFlickrApi(", "")
    respStr = respStr.rstrip(")")
    return json.loads(respStr)

def main(*args):
    while True:
        try:
            response = urllib2.urlopen(FLICKR_API_ENDPOINT+"?"+"api_key="+FLICKR_API_KEY+"&format=json&method=flickr.interestingness.getList&per_page=500&extras=o_dims")
            photos = convertToJSON(response.read())
            for p in photos['photos']['photo']:
                try:
                    height = str(int((float(265) / float(p['o_width'])) * float(p['o_height']))) + "px"
                except:
                    height = str(int(265 * .66)) + "px"
                url = "http://farm"+str(p['farm'])+".static.flickr.com/"+str(p['server'])+"/"+str(p['id'])+"_"+str(p['secret'])+".jpg"
                pageURL = "http://www.flickr.com/photos/"+p['owner']+"/"+p['id']
                opener = urllib2.build_opener()		
                values = {
                    'token' : CIL_API_TOKEN,
                    'event_code' : CIL_EVENT_CODE,
                    'content' : '<div style="width:100%;"><a href="'+pageURL+'" target="_blank"><img style="width:265px; height:'+height+'; margin:0 auto; border:none;" src="'+url+'"/></a></div>'}
                data = urllib.urlencode(values)
                response = opener.open(CIL_API_ENDPOINT + CIL_API_CONTENT_REQUEST, data)
                time.sleep(15)		
        except:
            pass

if __name__ == '__main__':
    sys.exit(main(*sys.argv))