
Authorization
Our REST API service uses key-based authorization that can be managed in your Account page. You can find your API key in the form of a 64-character string. But please note that we use this unique key to identify your account, so please do not share it with anyone.
All client requests are authorized using valid API keys via a specific HTTP header or query string. Query strings take priority over the HTTP header, so query strings will be considered if you send both at the same time.
Sending API Key via Query String
In order to authorize requests using the "
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 the "
X-RMAuth
" HTTP header method, you need to send it as follows:
<HTTP-METHOD> <domain>/api/<version>/<path> X-RMAuth: <api_key>
Unauthorized Requests
If you send invalid API keys, you will get a response with HTTP 403 Forbidden status and the following payload:
{ "status": { "code": null, "messages": ["API key is not valid"] }, "data": null }
Author API
The author API supports creating users that can be used to create drafts.
Creating Authors
Creates an author and sets its role as guest editor. You can modify user roles in your dashboard as desired once the author is created.
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/" }
Drafts API
The draft API supports creating drafts that can be used to publish content on your site.
Creating Drafts
Creates a draft and sets current user as author by default.
POST /api/1.3/drafts
Important
We provide another endpoint for backward compatibility with 1.1 API version, 1.3 is the preferred endpoint.
POST /api/1.1/posts
Parameters
Name | Type | Description |
---|---|---|
headline | String | Headline - Required |
body | String | Body - Optional |
manual_basename | String |
Slug - Optional - It's automatically generated based on
headline , by default
|
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 |
photo_credit | String | Photo credit - Optional |
manual_image_crops | Object | Crops calculated when uploading image - Optional |
video | String | Video URL - Optional |
listicle | Object | Listicles, refer to listicles document for more information - Optional |
roar_author_ids | Array of integers | Author IDs - Optional |
roar_specific_data | Object | Custom fields - Optional |
created_ts | Integer |
Publishing date - Optional - Defaults to timestamp for publish action
|
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.- In order to control the place where the listicles are going to be rendered inside the body, it's required to introduce a listicle HTML tag.
- By default,
roar_author_ids
is automatically populated with the ID of the user identified with the API key sent in request.
Response
The response can contain several fields, but we would like to highlight some of them that were specially requested:
Name | Type | Description |
---|---|---|
post_url | String | URL of the draft when it's published |
draft_url | String |
Composited by
post_url + "?draft=1" , which enables users to see the draft page
|
slug | String |
URL path from
post_url |
Editing Drafts
Edits a draft.
PUT /api/1.3/drafts/<id>
Parameters and Response
The same specification from creating drafts applies here.
Publishing Drafts
Publishes a draft.
PUT /api/1.3/drafts/<id>
Parameters and Response
In addition to the specification from updating drafts, an "action" parameter with value "publish" can be sent to API in order to publish a draft.
Name | Type | Description |
---|---|---|
action | String |
Action to be performed.Optional.Choices:
|
Note
draft_url
is not returned in response payload when publishing a draft.- Stored data from the draft will be published if not received updated data is coming within request payload.
Posts API
The post API supports updating already published content, and unpublishing posts from site.
Editing Posts
Edits a post.
PUT /api/1.3/posts/<id>
Parameters
Name | Type | Description |
---|---|---|
headline | String | Headline - Required |
body | String | Body - Optional |
manual_basename | String |
Slug - Optional - It's automatically generated based on
headline , by default
|
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 |
photo_credit | String | Photo credit - Optional |
manual_image_crops | Object | Crops calculated when uploading image - Optional |
video | String | Video URL - Optional |
listicle | Object | Listicles, refer to listicles document for more information - Optional |
roar_author_ids | Array of integers | Author IDs - Optional |
roar_specific_data | Object | Custom fields - Optional |
created_ts | Integer | Publishing date - Optional - Defaults to timestamp for publish action |
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.- In order to control the place where the listicles are going to be rendered inside the body, it's required to introduce a listicle HTML tag.
- By default,
roar_author_ids
is automatically populated with the ID of the user identified with the API Key sent in request.
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. |
slug | String |
URL path from
post_url .
|
Note
- Unlike drafts API, posts API doesn't return
draft_url
in response payload unless post was unpublished.
Unpublishing Posts
Unpublishes a post.
PUT /api/1.3/posts/<id>
Parameters and Response
In addition to the specification from updating posts, an "action" parameter with value "unpublish" can be sent to API in order to unpublish a post.
Name | Type | Description |
---|---|---|
action | String |
Action to be performed.Optional.Choices:
|
Note
draft_url
is returned in response payload when unpublishing a post.
Listicles
Our drafts API and posts API support listicles creation, listicles are a set of particles inside a post and you can control the place where they are going to be rendered inside the body by introducing a listicle HTML tag in post body parameter.
Parameters
Name | Type | Description |
---|---|---|
items | Array of objects | Items, particles of the listicle - Optional |
settings | Object | Settings - Optional |
Item Parameters
Name | Type | Description |
---|---|---|
headline | String | Headline - Optional |
media | String | Media, usually a raw shortcode to be rendered above or below body - Optional |
is_image | Boolean |
For backward compatibility, it must be
true if media is an image - Optional
|
image_id | Integer | ID of the uploaded image - Optional |
caption | String | Caption - Optional |
credit | String | Photo credit - Optional |
manual_image_crops | Object | Crops calculated when uploading image - Optional |
body | String | Body - Optional |
Note
image_id
can be found asid
in Image API response when uploading or editing images.- It's possible to use image shortcodes in
media
field, you can find them in "shortcode" field inside the payload responsewhen uploading images with Images API.
Setting Parameters
Name | Type | Description |
---|---|---|
body_text_above | Boolean |
Controls body position above or below media.Optional. Defaults to
false .
|
layout_type | Integer |
Layout type.Optional. Defaults to
1 .Choices:
|
Example
The parameters described above should be sent as part of the payload for creating/updating drafts/posts, as the following:
{ "headline": "This is an awesome post!", "body": "<p>foo</p><listicle></listicle><p>bar</p>", "listicle": { "items": [ { "headline": "Listicle 1", "body": "Here is some content" } ], "settings": { "body_text_above": true } } }
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 runner sites, we have the following ratios configured:
Title | Code | Sizes |
---|---|---|
Super Wide | 3x1 |
|
Wide | 2x1 |
|
Medium | 3x2 |
|
Square | 1x1 |
|
Tall | 9x16 |
|
Widescreen | 16x9 |
|
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
Name | Type | Description |
---|---|---|
image_url | String | A image URL location - Optional |
caption | String | Caption - Optional |
photo_credit | String | Photo credit - Optional |
alt | String | Alt/Title - Optional |
Parameters
Name | Type | Description |
---|---|---|
image_url | String | A image URL location - Optional |
caption | String | Caption - Optional |
photo_credit | String | Photo credit - Optional |
alt | String | Alt/Title - Optional |
Note:
- Multiple files can be also sent as part of HTTP request. These parameters are used only if
image_url
is not used in HTTP request. - For requests with "multipart/form-data" content type, files should be named with "file".
Example with multipart/form-data
POST /api/1.3/images HTTP/1.1 HOST: <domain> x-rmauth: <api key> authorization: Basic <base64 encoded credentials> content-type: multipart/form-data; boundary=----WebKitFormBoundarym59pe8dwmBaESksR content-length: <content length> ------WebKitFormBoundarym59pe8dwmBaESksR Content-Disposition: form-data; name="file"; filename="image.png" Content-Type: image/png <file content> ------WebKitFormBoundarym59pe8dwmBaESksR--
Note
Files to be considered for uploading must be named with "file" string.
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%2F<id src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/origin.jpg">", "35x35": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/35x35.jpg">", "1200x800": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/1200x800.jpg">", "480x270": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/480x270.jpg">", "700x1245": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/700x1245.jpg">", "980x": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/980x.jpg">", "600x": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x.jpg">", "600x600": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x600.jpg">", "960x540": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/960x540.jpg">", "600x300": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x300.jpg">", "210x": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/210x.jpg">", "300x": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/300x.jpg">", "600x400": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x400.jpg">", "1200x600": "<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/1200x600.jpg">" }, "manual_image_crops": { "16x9": { "width": 512, "top": 222, "height": 289, "left": 0, "sizes": [ "960x540", "480x270" ] }, "2x1": { "width": 512, "top": 255, "height": 256, "left": 0, "sizes": [ "1200x600", "600x300" ] }, "3x2": { "width": 512, "top": 169, "height": 342, "left": 0, "sizes": [ "1200x800", "600x400" ] }, "1x1": { "width": 109, "top": 402, "height": 109, "left": 0, "sizes": [ "600x600" ] }, "9x16": { "width": 117, "top": 303, "height": 208, "left": 0, "sizes": [ "700x1245" ] } }, "filename": "image_hmXa6R.jpg", "width": 512, "media_html": "<img src=\"<img src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/980x.jpg">\" id=\"89b1c\" class=\"rm-shortcode\" data-rm-shortcode-id=\"7229TA1498262817\" data-rm-shortcode-name=\"rebelmouse-image\" >", "shortcode": "[rebelmouse-image <id> is_animated_gif=false crop_info=\"%22%7B%22image%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F<id expand="1]"," original_size="\"512x511\"" src="https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/origin.jpg">" }</id></id>
For 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 |
caption | String | Caption - Optional |
photo_credit | String | Photo credit - Optional |
Manual Image Cropping
Manual image cropping depends on the ratios that have been configured for the site. It must be an object, whose keys must be the ratio codes. 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 | Height of the original image |
imgWidth | Integer | Width 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 from uploading images. Only one image can be edited per request.
Webhooks
Webhooks allow you to receive notification of certain events from the RebelMouse platform. HTTP POST requests are performed for the configured URL you provide to 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 will receive the following information:
Name | Type | Description |
---|---|---|
post_id | Integer | ID of the post |
post_url | String | URL of the published post |
Click here for more on RebelMouse Public API v1.2.