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

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

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.

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

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.