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

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

Response

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