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.