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