Drafts API

The draft API supports the creation of new drafts, updating saved drafts, and publishing drafts on site.

Creating drafts

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

POST /api/1.3/drafts

Parameters

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 the headline field. Depending on the permalink settings configured, and in order to prevent duplicates, the id field might be appended. In any case, we store the final value in the 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 integers	Section IDs - Optional
primary_section	Integer	Primary section ID - Optional It must be added to sections field if any.
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
image_size	String	Size of the uploaded lead image with format <width>x<height> - 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
teaser_image_size	String	Size of the uploaded teaser image with format <width>x<height> - 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	Object	Particles (also known as listicles), refer to Listicles document for more information - Optional
product	Object	Product, refer to Products 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
updated_ts	Integer	Timestamp of last update date - Optional Behavior: Defaults to current timestamp unless a new value is sent in payload, or It keeps the saved value if prevent_modifying_updated_ts query parameter is received (on updates only). It must be expressed in UTC-based time
applenews_article	Boolean	Controls whether the article is going to be sent to Apple News - Optional - Defaults to false
ee_layout_name	String	Entry Editor layout name - Optional
provider_post_id	String	External Post ID. It can be set only when creating drafts/posts, not on edit.

Note

• For backward compatibility, the primary_section and sections fields are eligible by title using insensitive case mode. "Home" or 0 (zero) can be passed if you want to set a post in homepage.

• image_id, teaser_image_id, and social_teaser_image_id can be found as id in the Image API response.

• manual_image_crops, teaser_manual_image_crops, and social_teaser_manual_image_crops can be also found as manual_image_crops in the Image API response.

• image_size and teaser_image_size can be also found as shortcode_params.original_size in the Image API response. You can also use width and height and send it in format "<width>x<height>".

• Similar to the body field, the media field can be used to store HTML content. However, it is most often used to store a shortcode that will be placed at the top of the page.

• The video field must be an embeddable URL since it’s rendered as the source of an iframe element.

• The Scraper API provides shortcode and embeddable URL. Using it 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 where listicles will be rendered inside the body, it is 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 articles will be displayed according to the time zone configured for your site. Ask your account manager if you would like to modify this.

• Publishing articles to Apple News requires configuration in your site with access key and secret. Ask your account manager if you would like to use this feature.

Roar Specific Data

roar_specific_data is a schema-less object field and is intended for storing any extra information as is deemed necessary.

It can also be used 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

Note

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

Recipes

Our recipes feature is explained in detail in this document.

Custom URLs

Important

This is an experimental feature. If you are interested in exploring its capabilities, please 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.

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"
path	String	Path - Required

Note

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

Important

In order to prevent unexpected issues, avoid using encoded paths, use always decoded paths instead.

Example

Considering a JSON payload containing a post, this portion shows an example of the page_list attribute.

...
"page_list": [
     {
         "view": "web",
         "path": "tutorials/posts/custom-slugs-guide"
     }
]
...

Response

The response will most likely contain several fields, but the following are some important ones to take note of:

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.

Important

For PUT requests, if roar_author_ids is sent with no value, then the user identified with the API key received is assigned as the unique author.

If roar_author_ids is not sent, then the author value will not be modified.

Publishing drafts

Publishes a draft.

PUT /api/1.3/drafts/<id>

Parameters and Response

In addition to the specifications from updating drafts, an “action” parameter with the value “publish” can be sent to API in order to publish a draft.

Name	Type	Description
action	String	Action to be performed. Optional. Choices: "publish"

Note

• draft_url is not returned in the response payload when publishing a draft.

• Stored data from the draft will be published if unreceived updated data is coming within request payload.

Deleting drafts

Deletes a draft.

DELETE /api/1.3/drafts/<id>

Response

The response payload is an empty object.

{}

List drafts

Fetch all drafts ordered by most recently published.

GET /api/1.3/drafts

Parameters

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

Response

Returns an array of objects with the same specifications as Creating drafts.

Get a single draft

GET /api/1.3/drafts/<id>

Response

The same specifications as Creating drafts apply here.