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

orphan:

Name	Type	Description
headline	String	Headline - Required
body	String	Body - Optional
basename	String	Slug - Optional - It’s automatically generated based on headline, by default
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
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
created_ts	Integer	Publishing date - Optional - Defaults to current timestamp

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.
• By default, roar_author_ids is automatically populated with the ID of the user identified with the API Key sent in request.

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

Recipes

Recipes feature is highly explained in this document.

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.

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.

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

Note

Unlike the rest of endpoints to list posts, this endpoint returns articles in draft status too.

Parameters

Name	Type	Description
basename	String	Basename – Required

Response

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