COVERITLIVE API - CONTENT/CREATE (V. 2.0)

The Request

This method allows you to post content directly into your live event from a custom application. Once set up you will be able to auto-publish content (including text and multimedia) from external sources such as 3rd party image or content management systems. Set it up once and let the API do all the work during your event. This allows CoveritLive to be integrated with just about any application that can connect to the web.

URL:
https://api.coveritlive.com/remote/2/content/create
Response Formats:
JSON
HTTP Method(s):
POST
API Rate Limited:
true (2 requests per rolling 5 second period)
In addition to the parameters listed in the Request Parameters section, the content/create method also includes the following parameters:

Parameter Description Required
event_code The event code for the event which the content will be added to. Each CiL event that is created is assigned a unique event code that identifies it in the database - The event owner can find this value after creating a new event, by selecting the "altcast_code" which is found in their Viewer Window embed code (e.g. the event code is "46e6cd22b5" in "altcast_code=46e6cd22b5"). This value is also returned by the event/list API method. yes
content_type

The default content type for an item created through the content/create API call is a writer post. This is an html or text post that can have an optional display name or avatar. Set the content_type request parameter to create a particular item other than a writer post. Depending on this value, there may be additional request parameters that are specific to the content type (which are listed below). Possible values for content_type include:

html - an html or text post. Differs from a writer post in that it never has a display name or avatar.

rss - an "RSS" item, which is formatted like an RSS item post from the Search panel in Event Studio. Includes a title, link, description and image.

 no
content This is the content which will be inserted into your event. May include HTML markup. May not be > 5000 characters in length. yes

Additional request parameters when content_type is not set:


Parameter Description Required
writer_name If provided AND the target event has enabled Display Names, the parameter provided here will be used for that display name. no
avatar_uri If provided the URI of an image that will be used as the avatar for the content entry being inserted. Images are displayed at 48x48 pixels. If image provided does not match these dimensions it will be auto-resized in the CoveritLive Viewer Window. no
raw_data If provided this contains any data structure about the content. It is not manipulated by the software and will appear exactly like it was input when pulling content through the event/data API call. no

Additional request parameters when content_type is set to "rss":


Parameter Description Required
published_status

Indicates whether the item will be added to the SmartStream in the Event Studio, or if it will be added directly to the live event. Possible values include:

live - item will be added directly to the live event.

moderated - item will be added to the Smart Stream in the Event Studio.

 yes (if content_type request parameter is set)
tag_color

The tag_color parameter can be populated whether content is moderated or not. This will "tag" the item to be added to the moderation SmartStream with that particular color. Possible values include:

red

yellow

green

orange

blue

coral

purple

brown

 no
tag_category

The tag_category parameter can be populated (used with or without tag_color) to tag content making it searchable by tag_category in the moderation SmartStream. If there are multiple tags, separate all tags with comma symbol. Sample values include:

Popular

Most Liked

cats

sports,soccer

 no
item_id The id of an existing item in the event. The item currently being created will be inserted chronologically after the existing item in the event. This parameter should only be populated if published_status is set to "live". no
title The title of the RSS item. yes
description The description or content of the RSS item. yes
link A URL associated with the RSS item. The link and title will be combined into an anchor tag. yes
image An optional image to include in the RSS item display no

Additional request parameters when content_type is set to "html":


Parameter Description Required
published_status

Indicates whether the item will be added to the SmartStream in the Event Studio, or if it will be added directly to the live event. Possible values include:

live - item will be added directly to the live event.

moderated - item will be added to the Smart Stream in the Event Studio.

 yes (if content_type request parameter is set)
tag_color

If the published_status request parameter is set to "moderated", the tag_color parameter can also be populated. This will "tag" the item to be added to SmartStream with that particular color. Possible values include:

red

yellow

green

orange

blue

coral

purple

brown

 no
tag_category

The tag_category parameter can be populated (used with or without tag_color) to tag content making it searchable by tag_category in the moderation SmartStream. If there are multiple tags, separate all tags with comma symbol. Sample values include:

Popular

Most Liked

cats

sports,soccer

 no
item_id The id of an existing item in the event. The item currently being created will be inserted chronologically after the existing item in the event. This parameter should only be populated if published_status is set to "live". no
raw_data If provided this contains any data structure about the content. It is not manipulated by the software and will appear exactly like it was input when pulling content through the event/data API call. no
Usage Notes:
  • This method is subject to rate limiting. Rate limiting is set at 2 requests every 5 second period. If this limit is exceeded a rate_limit_exceeded error will be returned. If this error is encountered, please reattempt submission after a period of 5 seconds has elapsed.
  • By default API provided content will be styled to appear exactly like the content type it is set to. To customize the content design please include HTML styling and/or images.
  • After setting up your custom application we strongly recommend testing the API provided content in a Test event to ensure your content and all styling appears as intended.
  • If including images in your content, it is recommended that you explicitly set their CSS height property. This allows CoveritLive to properly calculate viewer window scrolling positions to help provide the optimal reading experience for your users.

The Response

The id of a successfully created content item is returned in the data field of a general response. This field will consist of a item_id field, which contains the item id. Items can be further interacted with using the content/* API calls.

Please Note: If the published_status request parameter is set to "moderated", the item_id will NOT be returned in the response. This is because moderated items are added to the SmartStream, and cannot be further interacted with through the API.

Example response to a successful content/create request:


{
	"result": "success",
	"message": "true",
	"type": "content",
	"action": "create",
	"version": 2,
	"data":{
		"item_id" : "22185041"
	}
}

Please Note: If the item_id request parameter has been included, the item created was an inserted item. In that case its id is returned in a field called insert_id, to distinguish it from regularly created content items. Inserted items can be further interacted with using the insert/* API calls.

Example response to a successful content/create request if the item_id request parameter has been included:


{
	"result": "success",
	"message": "true",
	"type": "content",
	"action": "create",
	"version": 2,
	"data":{
		"insert_id" : "22185041"
	}
}

content/create Error Responses

A variety of error responses (in addition to the common error responses) to content/create requests, and instructions on how to rectify them:

result response message response solution
rate_limit_exceeded Request denied because more than 2 requests made during last 5 seconds. Only 2 content/create request can be made per rolling 5 second period. Ensure any programs interacting with the CiL API obey this threshold.
missing_content_param Required parameter empty: content Ensure the content request parameter is present when making a content/create request.
invalid_content_param Exceeded maximum content length of: 5000 Ensure the content request parameter is does not exceed 5000 characters in length (including markup).
missing_published_status_param Required parameter empty: published_status. Ensure the published_status request parameter is present if the content_type parameter has been set.
invalid_published_status_param The published_status parameter was invalid. Valid values include: "live", "moderated". Ensure the published_status request parameter is set to a valid value if it is included.
missing_title_param Required parameter empty: title. Ensure the title request parameter is present if the content_type parameter has been set to "rss".
missing_description_param Required parameter empty: description. Ensure the description request parameter is present if the content_type parameter has been set to "rss".
missing_link_param Required parameter empty: link. Ensure the link request parameter is present if the content_type parameter has been set to "rss".
invalid_tag_color_param The tag_color parameter contained an invalid value. Valid values include: red, yellow, green, orange, blue, coral, purple, brown. Ensure the tag_color request parameter is set to a valid value if included.
invalid_item_id The item_id request parameter did not contain a valid item id. Ensure the item_id request parameter contains an id corresponding to an existing item in the event.
invalid_item_id_published_status item_id parameter cannot contain a value when published_status parameter set to "moderated" Ensure the item_id request parameter only contains a value if the published_status request parameter is set to "live".