Public API v1.2 - Roar/Runner
This in the current version of the API
RebelMouse Public API version 1.2 is available as of August 16th, 2016. The older version of the API (Public API version 1.1) will be deprecated on December 1st, 2016. Please make sure to switch over any and all calls to the new API by that time.
READ REQUESTS :
FRONTPAGE POSTS
Returns frontpage posts.
https://{roar_domain}/api/1.2/posts/frontpage?limit={limit}&offset={offset}
<strong>Argument Required Default Description Example</strong>limit no 10 number of posts to return 1offset no 0 number of posts to skip 10
POSTS BY SECTION
Returns section's posts.
https://{roar_domain}/api/1.2/posts/section?section_name={section}&limit={limit}&offset={offset}
<strong>Argument Required Default Description Example</strong>limit no 10 number of posts to return 1offset no 0 number of posts to skip 10section_name yes - section's url apps
POSTS BY AUTHOR
Returns author's posts.
https://{roar_domain}/api/1.2/posts/author?author_name={author_name}&limit={limit}&offset={offset}
<strong>Argument Required Default Description Example</strong>limit no 10 number of posts to return 1offset no 0 number of posts to skip 10author_name yes - author's name luladog
POSTS BY TAG
Returns posts by tag.
<strong>Argument Required Default Description Example</strong>limit no 10 number of posts to return 1offset no 0 number of posts to skip 10roar_domain yes - roar domain positivemousetag yes - tag pythonexclude_tags no - tags to exclude (comma separated list) mouse
POSTS' DETAILS
Returns posts' details.
https://{roar_domain}/api/1.2/posts?ids={ids}
<strong>Argument Required Default Description Example</strong>ids yes - ids of posts 1,2,3
SITES' DETAILS
Return sites' details.
https://{roar_domain}/api/1.2/site/details?site_id={site_id}
<strong>Argument Required Default Description Example</strong>site_id yes - site's id 1
AUTHORS' DETAILS
Return authors' details.
https://{roar_domain}/api/1.2/authors?ids={ids}&access_token={access_token}
<strong>Argument Required Default Description Example</strong>ids yes - authors' ids 19access_token yes - access token bdQ0XiTDyR2eOsQHkCooS6CeBwgD4vAd81ux4UmTFx2qXfzeEphrCFGZuK8S5Fk6
AUTHORS' DETAILS BY NAME
Return authors' details by name.
https://{roar_domain}/api/1.2/authors/name?author_names={author_names}&access_token={access_token}
<strong>Argument Required Default Description Example</strong>author_names yes - authors' names positivemouseaccess_token yes - access token bdQ0XiTDyR2eOsQHkCooS6CeBwgD4vAd81ux4UmTFx2qXfzeEphrCFGZuK8S5Fk6
AUTHORS' DETAILS BY FACEBOOK ID
Return authors' details by facebook ids.
https://{roar_domain}/api/1.2/authors/facebook?fb_ids={fb_ids}&access_token={access_token}
<strong>Argument Required Default Description Example</strong>fb_ids yes - facebook ids 19323283access_token yes - access token bdQ0XiTDyR2eOsQHkCooS6CeBwgD4vAd81ux4UmTFx2qXfzeEphrCFGZuK8S5Fk6
OVERALL POSTS STATS
<strong>Argument Required Description Restrictions Example</strong>order yes The field for results to be ordered by Only "total_views" value is valid for now total_viewsperiod yes Period which ends now Only "1h", "6h", "12h", "24h", "7d", "30d", "lifetime" values are valid for now 7dlimit yes Number of records to return Positive integer, Max value = 30 10offset yes Number of records to skip Non-negative integer 5access_token yes Access token for the roar String bdQ0XiTDyR2eOsQHkCooS6CeBwgD4vAd81ux4UmTFx2qXfzeEphrCFGZuK8S5Fk6
Respons:
{ "status": { "code": 0, "messages": [] }, "data": { "report": { "records": [{ "post_id": 12312321, "total_views": 1234 }, { "post_id": 4859674589, "total_views": 4321 }, ... ] } }}
INDIVIDUAL POSTS STATS
<strong>Argument Required Description Restrictions Example</strong>period yes Period which ends now Only "1h", "6h", "12h", "24h", "7d", "30d", "lifetime" values are valid for now 7dids yes List of post IDs Positive long numbers separated by comma, Max number = 30 12312321,4859674589access_token yes Access token for the roar String bdQ0XiTDyR2eOsQHkCooS6CeBwgD4vAd81ux4UmTFx2qXfzeEphrCFGZuK8S5Fk6
Respons:
{ "status": { "code": 0, "messages": [] }, "data": { "report": { "records": [{ "post_id": 12312321, "total_views": 1234 }, { "post_id": 4859674589, "total_views": 4321 }, ... ] } }}
FACEBOOK WINS
<strong>Argument Required Description Restrictions Example</strong>period yes Period which ends now Only "1h", "6h", "12h", "24h", "7d", "30d", "lifetime" values are valid 7dids yes List of post IDs Positive long numbers separated by comma, Max number = 30 12312321,4859674589access_token yes Access token for the roar String bdQ0XiTDyR2eOsQHkCooS6CeBwgD4vAd81ux4UmTFx2qXfzeEphrCFGZuK8S5Fk6
Response:
{ "status": { "code": 0, "messages": [] }, "data": { "report": { "records": [{ "post_id": 567, "page_fans": 84872, "page_name": "HOT 107.9", "page_logo": "https://scontent.xx.fbcdn.net/hprofile-xpt1/v/t1.0-1/p50x50/1509847_10152819708755859_1441502743297395555_n.png?oh=909b90499656ccd816f5d9202526d5ff&oe=57549D5A", "page_url": "https://www.facebook.com/56194705858", "post_created_at": 1456822800, "post_likes": 5, "post_shares": 0, "post_comments": 0, "post_url": "https://www.facebook.com/Hot107.9/posts/10153962058115859" }, ... ] } }}
TWITTER WINS
<strong>Argument Required Description Restrictions Example</strong>period yes Period which ends now Only "1h", "6h", "12h", "24h", "7d", "30d", "lifetime" values are valid 7dids yes List of post IDs Positive long numbers separated by comma, Max number = 30 12312321,4859674589access_token yes Access token for the roar String bdQ0XiTDyR2eOsQHkCooS6CeBwgD4vAd81ux4UmTFx2qXfzeEphrCFGZuK8S5Fk6
Response:
{ "status": { "code": 0, "messages": [] }, "data": { "report": { "records": [{ "post_id": 234, "account_fans": 63500, "account_logo": "https://pbs.twimg.com/profile_images/706968590717681664/MfcERn0d_normal.jpg", "account_name": "The Dodo", "account_url: "https://www.twitter.com/statuses/708080524666007552", "tweet_created_at" :1457654527, "tweet_likes": 328, "tweet_retweets": 328, "tweet_url": "https://twitter.com/dodo/status/708080524666007552" }, ... ] } }}
Authorization
Our REST API service uses a key based authorization that could be managed in your Account page. You can find your own API key in form of a 64 character string, and note that we will be able to identifies you with it, so please do not share it.
All client requests are authorized using valid API keys via an specific HTTP header or query string. Query string takes priority over HTTP header, so query string will be considered if you send both at the same time.
Sending API key via query string
In order to authorize requests using "api_key
" query string, you need to send it as follows:
<HTTP-METHOD> <domain>/api/<version>/<path>?api_key=<api_key>
Sending API key via HTTP header
In order to authorize requests using HTTP header named "X-RMAuth
", you need to perform as follows:
<HTTP-METHOD> <domain>/api/<version>/<path> X-RMAuth: <api_key>
Unauthorized requests
If you send invalid API keys, you are going to get a response with HTTP 403 Forbidden status and the following payload:
{ "status": { "code": null, "messages": ["API key is not valid"] }, "data": null }Rawauthors.rst
Author API
The author API supports creating users that could be used to create drafts.
Creating authors
Creates an author and sets its role as guest editor.
POST /api/1.1/authors
Parameters
Name | Type | Description |
---|---|---|
first_name | String | First name - Required |
last_name | String | Last name - Required |
email | String | User email - Required |
password | String | User password - Required |
about_html | String | User biography - Optional |
image_id | Integer | ID of the uploaded image - Optional |
Note
image_id
can be found asid
in Image API response when uploading or editing images.
Response
{ "id": <id>, "name": "paulberry", "displayname": "Paul Berry", "about_html": "This is me", "bio": "", "photo": "https://<domain>/res/avatars/default", "fb_id": null, "profile_url": "https://<domain>/community/paulberry/" }Rawdrafts.rst
Drafts API
The draft API supports creating drafts that could be used to publish content on site.
Creating drafts
Creates a draft and sets current user as author by default.
POST /api/1.1/posts
Parameters
Name | Type | Description |
---|---|---|
headline | String | Headline - Required |
body | String | Body - Optional |
subheadline | String | Subheadline - Optional |
tags | Array of strings | Tags - Optional |
primary_tag | String | Primary tag - Optional |
sections | Array of strings | Sections - Optional |
primary_section | String | Primary section - Optional |
og_title | String | Social headline - Optional |
og_description | String | Social description - Optional |
image_id | Integer | ID of the uploaded image - Optional |
manual_image_crops | Object | Crops calculated when uploading image - Optional |
Note
primary_section
andsections
fields are eligible by title using insensitive case mode. "Home" can be passed if you want to set draft in homepage.image_id
can be found asid
in Image API response when uploading or editing images.manual_image_crops
can be also found asmanual_image_crops
in Image API response when editing images.
Response
The response can contain several fields, but would like to highlight some of them that were specially requested:
Name | Type | Description |
---|---|---|
post_url | String | URL for the draft when is published. |
draft_url | String | Composited by post_url + "?draft=1" , which enables users to see draft page. |
slug | String | URL path from post_url . |
Image API
The Image API supports uploading and editing images that could be used as splash post image, teaser, social teaser and even other features than posts such as authors creation.
Ratios
Every site in RebelMouse platform has its own image crops configured, these settings are useful when a image is going to be rezised or cropped. So they are considered in every process related to images, and each resized or cropped image has usually a different purpose depending on page type.
For Axios, we have the following ratios configured:
Title | Code | Sizes |
---|---|---|
FHD | 16x9 |
|
Wide | 2x1 |
|
Medium | 2x1 |
|
Tall | 1x1 |
|
Instant | 9x16 |
|
Uploading images
Upload a image sending its content as a part of HTTP request body or sending a URL as part of a JSON document.
POST /api/1.3/images
Parameters
Name | Type | Description |
---|---|---|
image_url | String | A image URL location - Optional |
Note
Multiple files can be also sent as part of HTTP request. They are used only if image_url
is not used in HTTP request.
Response
For a single image uploaded:
{ "is_animated_gif": false, "task_id": "c3e2a367-24cb-426f-9179-457a0e0ea9ec", "height": 511, "shortcode_id": "7229TA1498262817", "iptc": { "by-line": "", "caption/abstract": "" }, "id": <id>, "shortcode_params": { "is_animated_gif": false, "crop_info": "%22%7B%22image%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2FFor multiple images uploaded:
It takes the same schema for each image uploaded but in form of an array.
Editing images
Editing an image for creating some others with certain dimensions.
PUT /api/1.3/images/<id>Parameters
Name Type Description image_url
String A image URL location - Required manual_image_crops
Object Crop setting for resizing image - Optional Manual Image Crops
It depends on ratios configured per site. It must be a objects, whose keys must be the ratio codes and the values should contain the following information:
Name Type Description top
Integer Absolute top coordinate left
Integer Absolute left coordinate height
Integer Absolute height coordinate width
Integer Absolute width coordinate imgHeight
Integer Width of the original image imgWidth
Integer Height of the original image Example
{ "16x9": { "top": 222, "left": 0, "height": 289, "width": 512, "imgWidth": 512, "imgHeight": 511 }, "2x1": { "top": 255, "left": 0, "height": 256, "width": 512, "imgWidth": 512, "imgHeight": 511 }, "3x2": { "top": 169, "left": 0, "height": 342, "width": 512, "imgWidth": 512, "imgHeight": 511 }, "1x1": { "top": 402, "left": 0, "height": 109, "width": 109, "imgWidth": 512, "imgHeight": 511 }, "9x16": { "top": 303, "left": 0, "height": 208, "width": 117, "imgWidth": 512, "imgHeight": 511 } }Response
It takes the same schema than uploading images. Only one image is permitted to edit per request.
Rawwebhooks.rstWebhooks
Webhooks allows you to receive a notification to certain events from RebelMouse platform. HTTP POST requests are performed for the configured URL you provide us, these requests are formed with the following headers:
Name Value User-Agent RebelMouse/0.1 Mozilla/5.0 (compatible; http://rebelmouse.com) Gecko/20100101 Firefox/7.0.1 Content-Type application/json Published post
You can receive a notification when a post is published, you are going to receive the following information:
Name Type Description post_id
Integer ID of the post post_url
String URL for the published post