RebelMouse Public API

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

Note:

• image_id can be found as id 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

Note

• primary_section and sections 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 as id in Image API response when uploading or editing images.
• manual_image_crops can be also found as manual_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:

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.

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

Note

• primary_section and sections 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 as id in Image API response when uploading or editing images.
• manual_image_crops can be also found as manual_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:

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.

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

Item Parameters

Note

• image_id can be found as id 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

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:

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

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

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:

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:

Published Post

You can receive a notification when a post is published. You will receive the following information:

Click here for more on RebelMouse Public API v1.2.