Posts API

The post API supports updating already published content, and unpublishing posts from site.

Editing posts

Edits a post.

PUT /api/1.3/posts/<id>

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 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

Note

• 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

Note

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

Recipes feature is highly explained in this document.

Custom URLs

Important

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

Note

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.

Response

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.
slug	String	URL path from post_url.

Note

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

Unpublishing posts

Unpublishes a post.

PUT /api/1.3/posts/<id>

Parameters and Response

In addition to the specification from updating posts, an “action” parameter with value “unpublish” can be sent to 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.

Get a single post

Fetch a single post by ID.

GET /api/1.3/posts/<id>

Response

The same specification from Editing posts section applies here.

List posts

Fetch all posts ordered by recency on 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 30

Response

This resource returns an array of objects with the specification described on Editing 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 30

Response

This resource returns an array of objects with the specification described on Editing 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 30

Response

This resource returns an array of objects with the specification described on Editing posts.

List posts by tag

Fetch all posts by tag ordered by recency on publish date.

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 30

Response

This resource returns an array of objects with the specification described on Editing posts.

List posts by search phrase

Fetch all posts by search phrase ordered by recency on publish date.

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 30

Response

This resource returns an array of objects with the specification described on Editing posts.

List posts by basename

Fetch all posts by basename ordered by recency on publish date.

GET /api/1.3/posts/basename

Important

Unlike the rest of endpoints to list posts, this endpoint returns 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

This resource returns an array of objects with the specification described on Editing posts.