This page details the available functionality provided by the CircleMe Business REST API, the limits and sample parameters/responses.
Every request to the API endpoints will require valid credentials. Accounts can find their Access Token in a custom Dashboard. In this dashboard you will be able to reset the Access Token, immediately disabling the previous one from making requests to the API on your behalf.
This token should be treated as a password, therefore you should follow good practices to store it safely.
To consume the API each request will need to provide the token as X-AUTH-TOKEN header.
To ensure the service availability for all possible consumers a Rate Limit on a per-user (or per access token) basis is set in place. A limit of 30 requests per minute is established globally. That means that requests to all endpoints count for the Rate Limit.
Besides the number of request calls per minute the API will accept, there is also a Daily Limit of content cards available (agreed and set by contract). This means that an account with a hypothetical Daily Limit of 100 will be able to fetch at most 100 new cards on a 24h window timeframe. As long as the request Rate Limit is not exceeded, accounts can fetch all historically (previously fetched) cards but they won't have access to more than the Daily Limit every 24h 'time window'.
200 - OK
401 - Unauthorized
401 response is that the request didn't provide a valid X-AUTH-TOKEN header.403 - Forbidden
403.404 - Not found
500 - Internal server error
It is also worth noting that all API responses will be sent in JSON format.
GET /feed/itemsThis endpoint responds with a list of all Interest Id's assigned/approved for consumption to your account.
[
"350481",
"418206",
"211286",
"502803",
"504161",
"26619",
"231718"
]
GET /items/:id
This endpoint will respond with detailed data for a specific Interest requested by id.
{
"item_id": 350481,
"name": "Game of Thrones",
"description": "Game of Thrones is an American medieval fantasy television series created for HBO by David Benioff and D. B. Weiss, featuring a predominantly British and Irish cast. The series is based on author George R. R. Martin's best-selling A Song of Ice and Fire series of seven planned fantasy novels, the first of which is called A Game of Thrones. The series debuted in the U.S. on April 17, 2011.\r\nGame of Thrones has been extremely well received critically, and has garnered a loyal fanbase. The series was picked up for a second season on April 19, 2011, just two days after its premiere.\r\nThe cable television series closely follows the multiple storylines of the A Song of Ice and Fire series, and author Martin has stated that the show's pilot script was very faithful to his work. Set in the Seven Kingdoms of Westeros, where \"summers span decades and winters can last a lifetime,\" Game of Thrones chronicles the violent dynastic struggles among the kingdom's seven noble families for control of the Iron Throne; as the series opens, additional threats from the snow and ice covered region north of Westeros and from the eastern continent across a narrow sea are simultaneously beginning to rise.",
"thumbnail": "http://d241qdvc46llyt.cloudfront.net/items/pictures/380196/small/open-uri20120320-25171-1l5f0p6.jpg?1394708308"
}
GET /feedThis is the main endpoint for data consumption of the API and will respond with an array of cards containing posts about the Interests assigned to your account. Note that the only optional field in the feed response is the thumbnail, which may or may not appear in some cards.
lang
english and italian, defaults to english.
item_ids
GET /feed/items).
limit
50 at a time. Defaults to 20.
new_cards
before_date
date timestamps dating lower than (before/older than) this value (ISO 8601 format).
[
{
"id": "1004556",
"title": "Game of Thrones sound designer Paula Fairfield joins Con of Thrones lineup",
"body": "Game of Thrones sound designer Paula Fairfield joins Con of Thrones lineup http://winteriscoming.net/2017/05/09/game-thrones-sound-designer-paula-fairfield-joins-con-thrones-lineup/",
"source": "winteriscoming.net",
"link_url": "http://winteriscoming.net/2017/05/09/game-thrones-sound-designer-paula-fairfield-joins-con-thrones-lineup/",
"item_id": 350481,
"date": "2017-05-10T01:18:04.000Z",
"thumbnail": "http://d241qdvc46llyt.cloudfront.net/link/thumbnails/4595499/original/a3b5a9a8142474644a319422f464832f.:ext?1494375867"
},
{
"id": "1004548",
"title": "F1 Fanatic round-up: Liberty to distance F1 further from Ecclestone",
"body": "Liberty to distance F1 further from Ecclestone | F1 Fanatic Round-up http://www.f1fanatic.co.uk/2017/05/10/f1-fanatic-round-up-1005-3/",
"source": "f1fanatic.co.uk",
"link_url": "http://www.f1fanatic.co.uk/2017/05/10/f1-fanatic-round-up-1005-3/",
"item_id": 418206,
"date": "2017-05-10T01:16:46.000Z",
"thumbnail": "http://d241qdvc46llyt.cloudfront.net/link/thumbnails/4595474/original/a1e322bb5726f1de668abb4819d5df7d.:ext?1494375368"
},
{
"id": "1004439",
"title": "This chart tracks the user ratings for every episode of Game of Thrones",
"body": "This chart tracks the user ratings for every episode of Game of Thrones http://winteriscoming.net/2017/05/08/chart-tracking-game-of-thrones-imdb-user-episode-rankings/",
"source": "winteriscoming.net",
"link_url": "http://winteriscoming.net/2017/05/08/chart-tracking-game-of-thrones-imdb-user-episode-rankings/",
"item_id": 350481,
"date": "2017-05-09T21:15:20.000Z",
"thumbnail": "http://d241qdvc46llyt.cloudfront.net/link/thumbnails/4594515/original/6d1e08412e752e165a0b918e9d59cefe.:ext?1494361629"
}
]