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, as follows:

<listicle id="listicle-{post_id}"></listicle>

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
manual_basename String
Slug part - Optional
If received, this field is used as slug part, otherwise, we generate it based on headline field.
If not received and headline is empty, the basename will take the following form:
'particle-{id}'
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 response when uploading images with Images API.
  • Consider to ask your Account Manager for a help on configuring permalink settings if you want to start using listicle slugs.

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

Example with shortcode

{
  "headline": "This is an awesome post!",
  "body": "<p>foo</p><listicle></listicle><p>bar</p>",
  "listicle": {
     "items": [
       {
        "headline": "Listicle 1",
        "media": "[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%3Cid%3E%2Forigin.jpg%22%2C%20%22thumbnails%22%3A%20%7B%22origin%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%2235x35%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F35x35.jpg%22%2C%20%221200x800%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x800.jpg%22%2C%20%22480x270%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F480x270.jpg%22%2C%20%22700x1245%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F700x1245.jpg%22%2C%20%22980x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F980x.jpg%22%2C%20%22600x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x.jpg%22%2C%20%22600x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x600.jpg%22%2C%20%22960x540%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F960x540.jpg%22%2C%20%22600x300%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x300.jpg%22%2C%20%22210x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F210x.jpg%22%2C%20%22300x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F300x.jpg%22%2C%20%22600x400%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x400.jpg%22%2C%20%221200x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x600.jpg%22%7D%2C%20%22manual_image_crops%22%3A%20%7B%2216x9%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20222%2C%20%22height%22%3A%20289%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22960x540%22%2C%20%22480x270%22%5D%7D%2C%20%222x1%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20255%2C%20%22height%22%3A%20256%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x600%22%2C%20%22600x300%22%5D%7D%2C%20%223x2%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20169%2C%20%22height%22%3A%20342%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x800%22%2C%20%22600x400%22%5D%7D%2C%20%221x1%22%3A%20%7B%22width%22%3A%20109%2C%20%22top%22%3A%20402%2C%20%22height%22%3A%20109%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22600x600%22%5D%7D%2C%20%229x16%22%3A%20%7B%22width%22%3A%20117%2C%20%22top%22%3A%20303%2C%20%22height%22%3A%20208%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22700x1245%22%5D%7D%7D%7D%22%0A\" original_size=\"512x511\" expand=1]",
        "is_image": true,
        "image_id": <image_id>,
        "caption": "<p>Here is the caption</p>",
        "credit": "<p>Here is the credit</p>",
        "body": "Here is some content"
      }
    ],
    "settings": {
       "body_text_above": true
    }
  }
}