Listicles

Both our drafts API and posts API support listicle creation.

Listicles are a set of particles grouped together inside a post. Their placement (where they will be rendered inside the post body) can be determined by the use of a listicle HTML tag in the 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
headline_html	String	Headline as HTML - Optional If received, this field takes precedence over headline
manual_basename	String	Slug part - Optional If received, this field is used as slug part, otherwise, this is generated based on the value in the``headline`` field. If it is not received and the headline field is also empty, the basename will be as follows: 'particle-{id}'
media	String	Media; usually a raw shortcode to be rendered above or below the 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 the Image API response when images are uploaded or edited.
• Image shortcodes can be placed in the``media`` field and will be found in the “shortcode” field inside the payload response when uploading images with Images API.
• Ask your account manager for further help 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 using the following structure:

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