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.

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.