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.

Why RebelMouse Is the Best Content Marketing Platform

RebelMouse is a unique platform and company. The company was founded on the vision that media companies would need an always-modern solution to thrive in the new connected internet, and that brands would have to behave like new media companies and use the same platforms.

Keep reading... Show less

Why Premium Creative Agencies and CTOs Choose to Develop on RebelMouse vs. WordPress and Drupal

The Intersection of Design and Development: Where Your Clients Thrive

We started RebelMouse seven years ago knowing that there was a fundamental design flaw in the world of traditional CMSs: Every instance, on every platform, had to be updated independently. It's similar to an era when users had to manage their own Microsoft Exchange Server for email. The costs of managing, maintaining, and iterating on a CMS to keep it awesome and world class is typically a $10 million-a-year endeavor. But even then, these cost-prohibitive CMSs are still behind the times.

Keep reading... Show less

Native Multivariate Testing at Scale With RebelMouse

What Differentiates Our Approach

There are many popular tools that allow you to perform experiments and A/B tests on your users — primarily Google Chrome Experiments and Optimizely. But all of these solutions are JavaScript additions to your web page that sidestep the problem of old, outdated, and clumsy CMSs. These solutions work by calling on a third-party JavaScript library that rewrites a page after it's rendered. This approach adds extra page weight and creates strange user experiences due to having to wait for everything to load and be rewritten on the fly.

At RebelMouse, we've solved this in a very elegant way. At the core level of our platform, we can natively render different layouts and track the exact differences in performance when comparing a test to your other layouts.

Keep reading... Show less

Modern E-Commerce: Blur the Line Between Content and Design

Create Modular + Reusable Design Patterns on RebelMouse

Content saturation is an industry-wide problem, and the e-commerce space is no exception given that it's filled with big brands, small Etsy stores, and everyone in between all fighting for similar audiences. The best way to fight this symptom is to understand your audience and provide them with what they want.

Keep reading... Show less

Instagram-style E-commerce Features on RebelMouse

Revolutionizing E-commerce on RebelMouse

Whether you're a brand with a blog or a media company with a site, driving purchasing behavior and building an audience that uses your content to find things they love to buy is vital. We're very proud to have built out the same functionality that everyone is now used to on Instagram, with layovers on images that lead to products with attribution.

Keep reading... Show less

Building Premium Communities and User Journeys on RebelMouse

RebelMouse is much more than just a replacement for a traditional CMS. Our platform is a tremendous community-building experience. Today's social ecosystem has given us a seemingly limitless number of premium creators who understand how to create gorgeous and relevant content that drives the growth of their own audiences. These creators and influencers are either experts in certain topics, or heavily engaged in targeted content that drives their interests. They're not only consuming the content they're passionate about, but they're contributing to the conversation, too. The new role of the editor is not just to cover the most important topics and people around their expertise, but also to invite those preferred influencers into their community and get them to participate in creating premium content.

Read our deck here...

Keep reading... Show less

Dynamic Voting: Grow Traffic and Engagement Organically

Help your audience find its voice.

Creating quality content is no longer on marketers alone. We live in a universe of creators who are willing to not only consume content that resonates, but play a role in the creation, promotion, and conversations surrounding it.

Since the start of RebelMouse, we've been on a journey to create dynamic media that is easier for content creators to curate and amplify on social. It's why we've built an online engagement platform centered around the power of communities that thrive naturally in the digital ecosystem.

Keep reading... Show less

How to Monetize Your Website in Today’s Publishing Environment

In order to define distributive publishing, we have to ask the following question: If you have quality content, but nobody sees it, does it even exist? The answer is no, because your content needs to be supported in a way that lets it move seamlessly across all channels, especially site, search, and social. But let's take this question a step further: If you can't monetize your content to generate the support it needs, how do you create quality content in the first place?

Keep reading... Show less

RebelMouse Outperforms Every Other CMS. Here’s the Data to Prove It.

Our Core Web Vitals drastically outpace every competitor, and we have the receipts

In an effort to build user retention and increase conversions, publishers are making a common mistake. They're adding more features to their websites, including ad placements, but losing sight of the main revenue driver: user experience.

The key to unlocking user retention lies completely in site performance. Currently, publishers are trying to build optimized websites that translate easily across devices and platforms, but fail to deliver an experience that checks all their boxes and prioritizes their readers. It takes less than a second of delayed load time to turn away a user. This is why Google has made page speed a top ranking factor on search, and shepherded the entire open web's newfound prioritization on site performance.

Game Changer: Google's Core Web Vitals Announcement

Google cemented its seriousness about page experience with the announcement of its Core Web Vitals measurements in Google Search Console. Core Web Vitals are three specific metrics that Google uses to determine a site's overall usability. While these data points will evolve over time, the 2020 version of vitals consists of three specific metrics:

Largest Contentful Paint (LCP): A website's LCP is the time it takes to load the main content on a page. Google wants LCP to happen within 2.5 seconds of when a page first starts loading.

First Input Delay (FID): This metric quantifies a user's experience when trying to interact with unresponsive pages. This usually occurs between First Meaningful Paint (FMP) and Time to Interactive (TTI) (more on what these two mean below). You want your FID score to be low to prove the usability of your site. According to Google, pages should haven an FID of less than 100 milliseconds.

Cumulative Layout Shift Score (CLS): CLS determines how often your users experience unexpected layout shifts or changes on a page. To ensure visual stability, you want your CLS score to be low. Google wants pages to maintain a CLS score of less than 0.1.

From Google.

Google says Core Web Vitals scores will be considered across every page, and will be a ranking factor in its Top Stories feature. While relevant quality content will always be the most important, the page experience ranking is now a make-or-break metric for your site's survival.

"A good page experience doesn't override having great, relevant content. However, in cases where there are multiple pages that have similar content, page experience becomes much more important for visibility in Search."

—From Google's page experience announcement, May 2020

Core Web Vitals will determine every site's performance score. You can see your site's Core Web Vitals specifically via Google Search Console, but your website's overall page performance is measured using Google's PageSpeed Insights and Lighthouse tools.

At RebelMouse, we guarantee a performance score of 90 or higher via PageSpeed Insights. To do this, we've built out a platform infrastructure that exceeds industry standards on Google's key metrics, particularly its Core Web Vitals, outperforming most industry leaders.

You can read more about how we've mastered Google's KPIs here. But the truth is in the data. Below is table that provides a snapshot into how RebelMouse-powered sites score:

And here's what the scores look like for some of the biggest sites on the open web:

As you can see, there's a lot of data Google takes into account even outside of Core Web Vitals. Here's a quick summary of the other important metrics that Google trusts to measure page performance:

First Contentful Paint (FCP): This metric measures the time from click to the time when a user's browser renders the first bit of content from the Document Object Model (DOM), which is your site's HTML structure. According to Google, this is an important milestone for your readers because it provides signals that your page is loading.

First Meaningful Paint (FMP): This is the amount of time it takes the most important content, what Google calls "hero elements," to load on site. Hero elements are different for every site, but should be intuitive based on your content. This metric helps determine your site's usability.

Time to Interactive (TTI): This is the most important metric to keep an eye on. This is when the site is fully rendered and ready for user action. This is a critical point when slow load time can occur, usually because JavaScript or other complex content hasn't fully rendered. So, in short, think of TTI as how long it takes for your site to load in its entirety.

Total Blocking Time (TBT): TBT measures a page's load responsiveness to quantify how long a page is non-interactive prior to becoming interactive. You want your site to have a low TBT to maintain its usability.

Speed Index (SI): SI is the measurement of how quickly the contents of a page are populated. You want your speed index score to be as low as possible.

Creating quality content is only half the battle in 2020, and publishers are already burdened with the around-the-clock task of creating content that resonates. This is why quality content must be supported by modern technology that can keep up with the speed of the web. RebelMouse provides publishers with a CMS that supports the new content lifecycle with an editorial suite designed for reach on site, search, and social.

Click here to read more about our modern approach to web performance. If you want to make performance a priority, request a proposal today. We can easily transform your site into one of the fastest on the web, giving you increased user retention and better conversion rates than ever before.

A Modern Story of Web Performance From RebelMouse Founder + CEO Andrea Breanna

If I had more time, this website would have loaded faster

In the first months of 2020, we've focused at RebelMouse on page speed and performance. We worked very hard and found ways to take 90% of the sites we power to 90+ performance scores via Google's PageSpeed Insights tool — even with sites that are loaded with ads, embeds, third-party analytics, and other typical slow-loading elements. You can read more about our victories here.

A few months after we started this process, COVID-19 hit the world very hard. Suddenly, every media company was faced with a huge problem: Advertising fell off a cliff in what seemed like seconds. The only way to survive this unprecedented downturn is to grow traffic and control costs at the same time. So we started to shave our code and made our websites faster. We dropped costs just as dramatically as we were increasing scores.

Here are some surprises we found when doing this: If you want truly exceptional performance, none of the JavaScript and CSS frameworks that developers love so much make the cut. We thought the React version of RebelMouse was going to be the huge page speed breakthrough, until we realized the only way to achieve this goal was to write the code carefully and refactor it endlessly until it was as short as possible. As any author will tell you, like editing a book or a blog post, the revision process is never really done. By stepping away from frameworks, and methodically shaving vanilla code, our customers continue to see major improvements in performance.

As we announced this to our site network and rolled it out publicly, many of our clients asked me personally, "How did you do it?" The answer is easy to understand regardless of how technical you may be. It's perfectly summarized in this wonderful quote attributed to Mark Twain:

"If I had more time, I would have written a shorter letter."
—Blaise Pascal, 1657 (and later, more famously Mark Twain)

The universe is sometimes very beautiful, and especially when you keep it simple. If you would like to start publishing on a site optimized for both speed and sustainability, request a proposal and let's start working together.

Google Launches Journalism Emergency Relief Fund for COVID-19 Publishers

Through the Google News Initiative, relief fund aids news outlets covering the virus

Small and medium-sized news organizations producing original content about the COVID-19 pandemic for their local communities could be eligible for money from Google.

The search engine announced a global Journalism Emergency Relief Fund through the Google News Initiative to support journalism during the crisis. Funds will range from the low thousands to tens of thousands depending on the size of the newsroom, according to Google.

Keep reading... Show less
Subscribe to Our Newsletter