Drafts API

The draft API supports creating drafts, updating already saved drafts, and publishing drafts on site.

Creating drafts

Creates a draft and sets current user as author by default.

POST /api/1.3/drafts


We provide another endpoint for backward compatibility with 1.1 API version:

POST /api/1.1/posts


Name Type Description
headline String Headline - Required
body String Body - Optional
basename String Slug - Optional - It’s automatically generated based on headline, by default
subheadline String Subheadline - Optional
type String
Post type - Optional
Choices available depending on configuration:
  • "page"
  • "image"
  • "video"
  • "product"
  • "event"
  • "place"
  • "recipe"

Defaults to:

  • "image" if an image_id or and image_external is set.
  • "video" if a video is set.
  • "page" if type is not explicitly set and if image_id, image_external and video aren’t set.
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 lead image - Optional
photo_credit String Photo credit for lead image - Optional
photo_caption String Photo caption for lead image - Optional
manual_image_crops Object Crops calculated when uploading lead image - Optional
teaser_image_id Integer ID of the uploaded teaser image - Optional
teaser_photo_credit String Photo credit for teaser image - Optional
teaser_photo_caption String Photo caption for teaser image - Optional
teaser_manual_image_crops Object Crops calculated when uploading teaser image - Optional
social_teaser_image_id Integer ID of the uploaded social teaser image - Optional
social_teaser_photo_credit String Photo credit for social teaser image - Optional
social_teaser_photo_caption String Photo caption for social teaser image - Optional
social_teaser_manual_image_crops Object Crops calculated when uploading social teaser image - Optional
media String Lead media - Optional
video String Embeddable video URL - Optional
listicle Array of objects Listicles, refer to Listicles document for more information - Optional
layout_name String Layout name - 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 current timestamp


  • 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, teaser_image_id, and social_teaser_image_id can be found as id in Image API response when uploading or editing images.
  • manual_image_crops, teaser_manual_image_crops, and social_teaser_manual_image_crops can be also found as manual_image_crops in Image API response when editing images.
  • Similarly to body field, media is a field that can store HTML content, but it’s mostly used to store a single shortcode to be placed at the top of the page.
  • video field must be an embeddable URL since it’s rendered as source of an iframe element.
  • Scraper API provides shortcode and embeddable URL, you can find:
    • embed.shortcode in order to use it in posts’ media or body field, or listicles content, and
    • videos.*.embed_url in order to use it in posts’ video field.
  • By default, in post pages, image_id takes precedence over media and video. And media takes precedence over video. This behavior can be changed in our Layout&Design page, ask your Account Manager for a help on this if needed.
  • 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.

Roar Specific Data

roar_specific_data is a schemaless object field and is intended for storing any information as necessary and also for certain supported features such as:

Keep Reading

Name Type Description
keep_reading_button_text String Text to be displayed on Keep Reading Button - Optional
keep_reading_hide_word_count Boolean Controls whether words count is going to be displayed - Optional - Defaults to false


Recipes feature is highly explained in this document.


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.
draft_url String Composited by post_url + "?draft=1", which enables users to see 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.
  • "publish"


  • 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.

List drafts

Fetch all drafts ordered by recency on publish date.

GET /api/1.3/drafts


Name Type Description
offset Integer Offset – Optional
limit Integer Limit – Optional, defaults to 10, maximum value is 30


This resource returns an array of objects with the specification described on Creating drafts.

Get a single draft

GET /api/1.3/drafts/<id>


The same specification from Creating drafts section applies here.