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.

NEW: Page Views per Particle Enabled for Google AMP

Increase mobile page views for every particle using Google AMP

RebelMouse has deployed an exciting update: We've enabled particle tracking in Google Analytics for articles using Google's Accelerated Mobile Pages (AMP) format, which means every particle now triggers a page view event upon scroll. Before, just one page view event would be logged when the mobile page initially loaded.

Not Familiar With What This Means? Read On

The days of static, flat media are over. Sites with low performance scores, obtrusive ad experiences, and poor content structure simply won't make it. Knowing these truths, the way we think of an article can no longer be static either.

An article today now takes several forms: short-form, long-form, listicle, slideshow, etc. Because of this, we've created a simple framework called Particle Assembler that accounts for all possibilities when building out content.

We playfully call each piece of your content a "particle," which is quite literally a "part" of an "article." These particles have become the core way to author content on RebelMouse, and are standalone elements that use their own imagery, title, and copy. For example, let's say you create a post that's titled, "The Best Place for Tacos in Austin." Each taco destination in this article will have a lead image, the name of the restaurant, its location, and a description of the restaurant with images of their food. Each of these restaurant highlights contain enough information to stand by themselves as individual posts.

Building particles in RebelMouse's Entry Editor.

And they do stand alone successfully when you're on RebelMouse — each particle can be shared separately on social and each will register as a unique page view thanks to our latest update. This is a critical part of our modern pageview methodology that ensures our publishers deliver an elegant user experience to readers while still capitalizing on a meaningful monetization strategy. For instance, not only is every particle now a page view on Google AMP, but it's also a new revenue opportunity. This is thanks to the various placement opportunities for ads we offer within our Particle Assembler.

ICYMI, Google AMP is the search engine's lightning-fast mobile experience. With this update, sites powered by RebelMouse will not only deliver the best AMP experience to their users, but they'll also earn the page views their content deserves, too.

See the Massive Difference

In just a short period after implementing this change, one client experienced a massive spike in AMP pages per user, where it jumped from 1.6 to 8.2:

Here's what their AMP pages per user looked like just prior to the update:

If you're interested in experiencing this type of growth and getting more page views for your mobile content, request a proposal today and let's start working together. If you're already on RebelMouse, email support@rebelmouse.com or talk to your account manager to learn more about particle views for Google AMP.

Primary Tags: Structure Your Site for Success

Dynamic taxonomy improves usability and propels SEO strategy

It's not a surprise that quality content can easily be spoiled by a poor site experience. This is why we're extremely proud of the lightning-fast sites we power. But speed is only the beginning of the user experience.

The temperature on platform dependency has cooled in recent years, revitalizing the value of site visits and search strategy. This is good news for both users and publishers who need site stability to survive. Because of this shift, RebelMouse focuses on three primary key performance indicators (KPIs) to measure site usability and health:

  • Sessions per User: The average number of site sessions that each user has in a given time period.
  • Pages per User: The average number of page views that each user has in a given time period.
  • Time per User: The average amount of time spent on site by each user.

In order for these metrics to shine, a site's architecture must be organized in a way that increases every user's time on site. The logic is simple: If a site is easier to navigate, the user will likely stick around longer. This is the gateway to user loyalty.

One important way we support these KPIs is through our intuitive tagging structure for content. Let's take a look at our primary tag functionality and how it can set up any site for success.

What Is a Primary Tag?

On RebelMouse, we give you the ability to use as many tags as needed on every article to help keep you organized. But there's also an option to assign one primary tag to a post. A primary tag is built on the same principle as a primary section. One tag lets you assign higher importance to certain pieces of content when processing and organizing your posts.

The Primary Tag and Tags sections in RebelMouse's Entry Editor.

The Benefits of Primary Tags

Dynamic Taxonomy: One of the primary benefits of using a primary tag is that it exposes the depth of content available to your users. Many publishers do this through the use of sections, which often turns out to be redundant and, in turn, ignored:

Sections can often be annoying to navigate and repetitive.

Using a variety of relevant tags for every article, rather than just repeating the same handful of sections, opens up more opportunities for targeted descriptors. For example, instead of using "Recipes" as a section over and over again, a primary tag can be used to create specific content flows for topics like "Vegetarian," "Soups," or "Cocktails."

Richer SEO: Since a primary tag exposes more information about your article, it also supplies more relevant data to Google's algorithm. Surfacing content in usable ways supports Google's mission to serve content based on audience behavior and intent instead of outdated and frowned-upon SEO methods like keyword stuffing. This approach is called white hat SEO, or ethical SEO.

By targeting specific interests, your dynamic tag structure will allow Google to more accurately understand your article's content and rank it accordingly. On RebelMouse, this creates a trickle-down effect, because users can click a tag and quickly get directed to more relevant articles, which boosts your SEO efforts further.

Here's how the site experience looks on RebelMouse-powered EcoWatch when viewing their primary tag "Plastics."

RebelMouse-powered EcoWatch takes advantage of a primary tag construct.

Improves Crucial KPIs: As mentioned before, RebelMouse traffic experts are constantly focused on improving the three KPIs that matter most to site usability and building audience loyalty. These metrics answer the following questions:

  • Frequency: How often are users coming to the site?
  • Depth: How many articles does each user consume?
  • Duration: How long is each user staying on the site?

Looking again at EcoWatch's use of primary tags, it's important to note that a primary tag is exposed on every one of their articles. They're also used in a left-hand navigation module that features the latest stories and trending topics:

Start Leveraging Primary Tags on RebelMouse

If you aren't on RebelMouse yet, request a proposal today and let's start working together to make sure your site is optimized for user growth. If you're already publishing on RebelMouse, and want to learn more about tagging best practices, contact your account manager or email support@rebelmouse.com.

Page Speed Is Crucial to Your Marketing Efforts

Most marketers don't prioritize page speed because they don't think it impacts their bottom line. However, page load has a direct impact on conversions and revenue.

Here's a very simple scenario, supported by industry data, to underscore why the way pages are built and powered is crucial for paid media initiatives and your overall business:

Let's say a paid media campaign drives 100,000 new visitors to a landing page that takes five seconds to load. Google says that 53% of mobile site visitors will leave a page that takes longer than three seconds to load. So of the 100K mobile site visitors you paid to bring to the page, ~50K are leaving immediately due to poor page performance alone.

Some studies even show that bounce rate increases approximately 100% for every two-second delay. So, if site load jumps to seven seconds, you'll pretty much lose all of the visitors your paid strategies brought in.

A Poor Site Experience Costs More Than You Realize

Page load plays a huge part in customer dissatisfaction, too. Continuing on with our previous example, let's classify the ~50K that didn't abandon the page as dissatisfied due to poor page performance. As HubSpot points out, 79% of them are less likely to buy again from the same website. That's ~40K visitors never coming back to the site due to poor page speed. The loss is even greater when you consider how valuable returning visitors are: They represent up to 48% of all transactions and spend almost 2x more than new visitors, according to Business Insider.

Plus, people love to spread the word about a bad experience, probably more than a good one. 40% of visitors who had a bad experience with a website's performance would tell a friend or a family member. So of your 50K dissatisfied visitors, 20K are talking negatively about your brand. If they tell only one person each, that's an opportunity cost of another 20K potential site visitors and customers.

The main takeaway? Your paid media has to work much, much harder when you neglect to optimize your site for performance.

Owned and Paid Media Should Work Together for Better Efficiency

And speaking of site improvements to help the bottom line, marketers can't overlook the value of owned content (e.g., articles, reviews, social feeds, etc.) and its impact on overall traffic and lead generation strategies. Sites tend to see significant lift in audience reach and conversion when content is paired with commerce: For e-commerce companies, content can account for up to 69% of total organic traffic. And, even more compelling, conversion rates have been 6x higher for companies that adopt content marketing.

RebelMouse's CMS makes it easy for brands to systematically optimize page speed performance and organic reach, which allows paid media to be more efficient.

RebelMouse allows clients to easily manage website layouts and components at any time, ensuring sites remain fast and are rewarded by Google and Facebook. Our platform features proprietary SEO tools designed to help clients optimize organic search with every post and better align paid and organic search strategies for increased efficiency. Similarly, our platform also includes proprietary social tools to organically build community and growth, and our data helps clients spot winning organic trends that can inform paid social media.

RebelMouse Is a Partner That Can Guide You

When it comes to content marketing, it's important to be mindful of the relationship between owned, earned, and paid media — it will only help your teams engage and convert more audiences into customers and brand loyalists. At RebelMouse, we're proud of how we work with brands and our ability to provide the expertise, best practices, and modern technology that help teams become better content marketers. If you're a brand marketer, feel free to reach out to us to learn how RebelMouse can help you be more strategic and effective in your content marketing efforts.

Related Articles

Target High-Value Users With Affinity Categories

Unlock valuable audience data and shape a new strategy

In today's landscape, quality content isn't enough — it's half the battle. Publishers need to produce shareable content backed by data to experience sustainable growth. At RebelMouse, we have a unique pageview methodology that provides an innovative user experience for every reader without sacrificing revenue and growth opportunities for publishers.

To do this, we track massive amounts of data across our platform through the use of custom-built Google Data Studio dashboards.

Click here to see the kind of growth our clients experience every day.

One of the best ways to discover more about your audience is by taking advantage of Affinity Categories. This feature breaks down audience demographics, including age, location, interests, and more. Affinity Categories are usually used to target audiences for ads, but we also use them to gain insights on what topics a site's visitors are interested in overall.

Normally, each category is listed out separately in Google Analytics. In the example shown above, our data experts split categories into separate levels to reveal different levels of audience depth. For instance, by splitting up the category News & Politics, we can better explore the detailed distribution of users interested in specific types of news:

  • News & Politics/Avid News Readers/Avid Political News Readers
  • News & Politics/Avid News Readers/Entertainment News Enthusiasts

From an editorial standpoint, this is useful because it allows publishers to determine and target varying levels of high-value users, improving the efficacy of a new content strategy or ad campaign.

If your site is already powered by RebelMouse, email support@rebelmouse.com to get a breakdown of your audience's Affinity Categories. If you aren't powered by RebelMouse yet, request a proposal today and start receiving the data you need to grow loyal followers at scale.

Related Articles

Subscribe to Our Newsletter