Subscribe to Our Newsletter

x

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

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 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

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 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:

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:
  • "publish"

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 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:

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:
  • "unpublish"

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 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

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:
  • 1: Regular listicle
  • 2: Slideshow
  • 3: Full screen

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
  • 1200x400
  • 600x200
Wide 2x1
  • 1200x600
  • 600x300
Medium 3x2
  • 1200x800
  • 600x400
Square 1x1
  • 600x600
  • 300x300
Tall 9x16
  • 700x1245
Widescreen 16x9
  • 1245x700


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": ""," 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.

You're almost there! Fill out the form below and a Rebel will contact you within one business day.

x

A Look Inside the Only Creative Agency Powered by Deep Technology

Strategic development of product that supports content distribution, conversion, and loyalty.

RebelMouse is a creative agency fueled by a publishing platform with deep technology. Our expertise is rooted in media and content marketing because there is no other team that understands distributive publishing better than we do. There is also no other CMS on the market today that provides content creators with the tools they need to unlock sustainable growth backed by sticky monetization methods. RebelMouse blends product and strategy together to move the needle where it matters most — organic traffic and user growth, conversion to loyalty, and revenue growth.

Keep reading... Show less

New URL Structure for Communities and Users

If you've been following RebelMouse for any length of time, you know that we've gone all in on the power of influencers and creators. This, in turn, has driven us to expand and enhance our community-building platform at an incredible rate. Since our network has grown several fold with no signs of slowing down, it's now time to change how our technology handles user and community URLs to prevent any confusion in the future, especially for clients of ours that employ multiple communities.

Keep reading... Show less

More Elements Available for Lazy Load

Lazy loading has been an available option in our Layout & Design tool for quite some time. In the world of computer programming, lazy loading is a design pattern that allows specific parts of your site to load in a certain order based on what the user needs to see first. Its use is suggested for common page elements such as related post lists, sidebars, and any others features of an article.

Keep reading... Show less

Manage Your Site's Global Settings

Create Your Powerful + Modern Publishing System

At RebelMouse, we use the term "lean tech" quite a bit. Lean tech is the opposite of what many publishers think may save their site in today's landscape: A big-box CMS publishing solution that is often costly to customize and maintain. In actuality, the key to sustainable growth and revenue is a leaner, full-stack tech solution that creates opportunities for growth not just on site, but on search and social, too.

Keep reading... Show less

Let Your Audience Tell Your Brand’s Story

United Airlines' "Her Art Here" Campaign Blends Engagement With Purpose

The digital landscape has reached a turning point. Publishers are trying to pick up the pieces and figure out how to create quality content and monetize it now that readers have loosened up their dependency on the major platforms. In the meantime, massive audience hubs like Facebook are trying to recover legitimacy and relevancy with better prioritization of privacy and user experience.

Keep reading... Show less

You're almost there! Fill out the form below and a Rebel will contact you within one business day.

x

How to Leverage Annotations in Google Analytics

When looking at your website data in Google Analytics (GA), it can be difficult to remember exactly what happened on a particular day to determine why certain data spikes or dips may have occurred.

For this reason, it's important to keep track of when changes are made to your site. Thankfully, GA allows you to easily do this using annotations. Annotations are short notes you can add to dates within Google Analytics reports.

Keep reading... Show less

Changing the Face of Tech: The Women of RebelMouse

Keep reading... Show less

A Guide to User Permissions on RebelMouse

On our platform, user roles range from base-level contributors all the way up to administrators. These roles are especially important when operating within the confines of our community dashboard, which brings multiple creators together to create and share within one large content hub.

The way each role interacts with others is completely customizable. The workflow is designed to streamline the edit, revision, and publishing process to make sure live content is not only perfect, but always optimized for site, search, and social. The way each team sets up their role structure is typically dependent on the number of writers employed, the amount of content published, and the cadence of posts.

Keep reading... Show less

RebelMouse Ad Integrations: Overview

Since the dawn of digital publishing, exactly how to make money on content has been a rocky road for publishers to navigate. The good news is that thanks to factors like user maturity, advancements in tech, and algorithms that deliver a new level of personalization, monetizing your site is easier than before. In previous years, it seemed like publishers were drowning in the revenue duopoly that is Facebook and Google, with little time to come up for air.

Keep reading... Show less