Posts API ¶

The post API supports updating already published content as well as un-publishing posts.

Creating posts ¶

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

POST /api/1.3/posts

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 contain several fields, but here are two important ones to take note of:

Name	Type	Description
`post_url`	String	URL for the draft when is published.
`slug`	String	URL path from `post_url`.

Editing posts ¶

Edits a post.

PUT /api/1.3/posts/<id>

Parameters¶

The same specification from Creating posts applies here, but the following additional parameters are available:

Name	Type	Description
`prevent_modifying_updated_ts`	Integer	Controls whether the `updated_ts` is going to be modified - Optional Defaults to `0`. It works only if a value is not sent in payload for `updated_ts` Choices available: `0` to allow updating `updated_ts` `1` to prevent updating `updated_ts`

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.

Response¶

The response structure here is the same as the response structure used for Creating posts.

Note

Unlike the drafts API, the posts API doesn’t return the draft_url in the response payload unless the post was unpublished.

Unpublishing posts ¶

Unpublishes a post.

PUT /api/1.3/posts/<id>

Parameters and Response¶

In addition to the specifications for editing posts, an “action” parameter with the value “unpublish” can be sent to the API in order to unpublish a post.

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

Note

draft_url is returned in response payload when unpublishing a post.

Deleting posts ¶

Deletes a post.

DELETE /api/1.3/posts/<id>

Response¶

The response payload is an empty object.

{}

Get a single post ¶

Fetch a single post by ID.

GET /api/1.3/posts/<id>

Response¶

The response structure here is the same as the response structure used for Creating posts.

List posts ¶

Fetch all posts ordered by most recent publish date.

GET /api/1.3/posts

Parameters¶

Name	Type	Description
`offset`	Integer	Offset – Optional
`limit`	Integer	Limit – Optional, defaults to 10, maximum value is 100
`provider_id`	Integer	Provider of Post – Optional, defaults to 20 (Public API) if `provider_post_id` is received in payload. Choices available: `0` Entry Editor `15` Custom Import `20` Public API
`provider_post_id`	String	External Post ID – Optional
`order_by`	String	Changes the order of posts, defaults to `recency` Choices available: `last_update` to start from newest `updated_ts` `oldness` to start from oldest `created_ts` `recency` to start from newest `created_ts` `popularity` to order by page views in last x days. x is defined in `order_by_period_in_days` parameter. x defaults to 7
`include_sections`	String	Section IDs to include, multiple values can be sent with a comma-separated string – Optional
`exclude_sections`	String	Section IDs to exclude, multiple values can be sent with a comma-separated string – Optional
`require_sections`	String	Selects posts that have all these sections selected, multiple values can be sent with a comma-separated string – Optional
`phrase`	String	Filter posts by phrase – Optional
`date_from`	Integer	Date to start filtering from – Optional
`date_to`	Integer	Date to end filtering to – Optional
`type`	String	Post type – Optional,
`order_by_period_in_days`	String	Number of days to use in `popularity`, defaults to 7 – Optional
`exclude_private`	Boolean	Excludes private posts – Optional
`include_tags`	String	Tags to include, multiple values can be sent with a comma-separated string – Optional
`include_fields`	String	Fields to include in response, multiple values can be sent with a comma-separated string – Optional
`exclude_fields`	String	Fields to exclude in response, multiple values can be sent with a comma-separated string – Optional

Response¶

An array of objects is returned with each object having the same structure as the response returned in Creating posts.

List frontpage posts ¶

Fetch all frontpage posts in editorial order.

GET /api/1.3/posts/frontpage

Parameters¶

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

Response¶

An array of objects is returned with each object having the same structure as the response returned in Creating posts.

List posts by section ¶

Fetch all posts by section in editorial order.

GET /api/1.3/posts/section

Parameters¶

Name	Type	Description
`section_name`	String	Section name – Required
`offset`	Integer	Offset – Optional
`limit`	Integer	Limit – Optional, defaults to 10, maximum value is 100

Response¶

An array of objects is returned with each object having the same structure as the response returned in Creating posts.

List posts by tag ¶

Fetch all posts by tag. All returned posts will be ordered by date with the most recently published appearing first.

GET /api/1.3/posts/tag

Parameters¶

Name	Type	Description
`tag`	String	Tag – Required
`offset`	Integer	Offset – Optional
`limit`	Integer	Limit – Optional, defaults to 10, maximum value is 100

Response¶

An array of objects is returned with each object having the same structure as the response returned in Creating posts.

List posts by search phrase ¶

Fetch all posts filtered by search phrase. All returned posts will be ordered by date with the most recently published appearing first.

GET /api/1.3/posts/search

Parameters¶

Name	Type	Description
`phrase`	String	Search phrase – Required
`offset`	Integer	Offset – Optional
`limit`	Integer	Limit – Optional, defaults to 10, maximum value is 100

Response¶

An array of objects is returned with each object having the same structure as the response returned in Creating posts.

List posts by basename ¶

Fetch all posts by basename. All returned posts will be ordered by date with the most recently published appearing first.

GET /api/1.3/posts/basename

Important

Unlike all other endpoints that list posts, this endpoint will return articles in draft status too.

Parameters¶

Name	Type	Description
`basename`	String	Basename – Required
`removed`	Integer	Removed posts – Optional, removed articles will be listed only if received

Response¶

An array of objects is returned with each object having the same structure as the response returned in Creating posts.

List posts sorted by page views ¶

Fetch published posts sorted by page views.

GET /api/1.3/posts/page_views

Parameters¶

Name	Type	Description
`period_in_hours`	Integer	Period of time in hours – Optional, defaults to 24
`offset`	Integer	Offset – Optional
`limit`	Integer	Limit – Optional, defaults to 10, maximum value is 100

Response¶

An array of objects is returned with each object having the same structure as the response returned in Creating posts.