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
manual_basename String
Slug part - Optional
If received, this field is used as slug part, otherwise, we generate it based on headline field.
Depending in permalink settings configured and in order to prevent duplicates, id field might be appended.
In any case, we store the final value in basename field, so take this into account if you want to fetch articles by basename.
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
badges Array of integers Badge IDs - Optional
page_title String Meta title - Optional - headline is rendered in post pages if empty
meta_description String Meta description - Optional - subheadline is rendered in post page if empty
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
page_list Array of objects Custom URLs - Optional
created_ts Integer
Timestamp of publishing date - Optional - Defaults to current timestamp
It must be expressed in UTC-based time


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

    <listicle id="listicle-{post_id}"></listicle>
  • By default, roar_author_ids is automatically populated with the ID of the user identified with the API Key sent in request.

  • The publishing date for your articles will be displayed accordingly to the time zone configured for your site. Ask your Account Manager if you want to modify it.

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


In order to use this feature, you need to add a <hr> element to body at the specific point you want to split your content.


Recipes feature is highly explained in this document.

Custom URLs


This is an experimental feature, ask your Account Manager to enable it for your site.

page_list allows you to store an extensive set of alternative paths for your articles where you can make them available for your visitors. This is not only useful for regular web post pages, but also for AMP pages.

Every page to be included to this list must have the following parameters:

Name Type Description
view String
Post page view - Required
Choices available
  • "web"
  • "amp"
path String Path - Required


If the field is set, the first "web" and "amp" page paths in the list will be used to contruct the corresponding post URLs per view. Otherwise, the post URL will be generated based on your permalink settings.


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
removed Integer Removed posts – Optional, removed articles will be listed only if received


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.