Articles

Summary of article endpoints

• GET /admin/api/articles - list all available articles for the current site.
• POST /admin/api/articles - create a new article.
• GET /admin/api/articles/1 - get data for a single article.
• PUT /admin/api/articles/1 - overwrite all attributes of a single article.
• PATCH /admin/api/articles/1 - merge new attributes into a single article.
• DELETE /admin/api/articles/1 - remove an article.
• PUT /admin/api/articles/1/data/key_1 - update data field of an article.
• DELETE /admin/api/articles/1/data/key_1 - remove a custom field from an article.

Related endpoints:

• GET /admin/api/articles/1/comments

List all available articles for the current site

GET /admin/api/articles

By default, this requests returns a list of all articles for the current site (newer first).

This endpoint also allows anonymous access that return only a list of published articles. Articles under private blog pages are not returned.

Example response (authenticated request):

Status: 200 OK

[
  {
    "id": 2,
    "title": "How I wrote my first article",
    "autosaved_title": "How I wrote my first article",
    "path": "how-i-wrote-my-first-article",
    "description": "",
    "recaptcha": null,
    "comments_count": 0,
    "public_comments_count": 0,
    "publishing": true,
    "published": true,
    "data": {},
    "title_format": null,
    "title_separator": null,
    "created_at": "2014-01-23T09:22:04.000Z",
    "updated_at": "2014-01-23T09:22:04.000Z",
    "published_at": "2014-01-23T09:22:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/articles/2",
    "public_url": "http://helloworld.voog.co/blog/how-i-wrote-my-first-article",
    "contents_url": "http://helloworld.voog.co/admin/api/articles/2/contents",
    "comments_url": "http://helloworld.voog.co/admin/api/articles/2/comments",
    "page": {
      "id": 3,
      "path": "blog",
      "title": "Blog",
      "content_type": "blog",
      "created_at": "2014-01-23T09:19:04.000Z",
      "updated_at": "2014-01-23T09:19:04.000Z",
      "published_at": "2014-01-23T09:19:04.000Z",
      "url": "http://helloworld.voog.co/admin/api/pages/3",
      "public_url": "http://helloworld.voog.co/blog",
    },
    "language": {
      "id": 1,
      "code": "en",
      "title": "ENG",
      "created_at": "2014-01-23T09:19:04.000Z",
      "updated_at": "2014-01-23T09:19:04.000Z",
      "url": "http://helloworld.voog.co/admin/api/languages/1"
    },
    "author": {
      "id": 1,
      "name": "John Smith",
      "url": "http://helloworld.voog.co/admin/api/people/1"
    },
    "seo": {
      "full_title": "How I wrote my first article – My new site",
      "title_format": "<page_title> <separator> <site_title>",
      "score": 87,
      "metrics": [
        {
          "key": "title_length",
          "score": 75,
          "result": "warning"
        },
        {
          "key": "description_length",
          "score": 100,
          "result": "pass"
        }
      ]
    }
  }, {
    "id": 1,
    "title": "Having sample news pieces?",
    "autosaved_title": "Having sample news pieces?",
    "path": "having-sample-news-pieces",
    "description": "",
    "recaptcha": null,
    "comments_count": 0,
    "public_comments_count": 0,
    "publishing": true,
    "published": true,
    "data": {},
    "title_format": null,
    "title_separator": "<",
    "created_at": "2014-01-23T09:19:04.000Z",
    "updated_at": "2014-01-23T09:19:04.000Z",
    "published_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/articles/1",
    "public_url": "http://helloworld.voog.co/blog/having-sample-news-pieces",
    "contents_url": "http://helloworld.voog.co/admin/api/articles/1/contents",
    "comments_url": "http://helloworld.voog.co/admin/api/articles/1/comments",
    "page": {
      "id": 3,
      "path": "blog",
      "title": "Blog",
      "content_type": "blog",
      "created_at": "2014-01-23T09:19:04.000Z",
      "updated_at": "2014-01-23T09:19:04.000Z",
      "published_at": "2014-01-23T09:19:04.000Z",
      "url": "http://helloworld.voog.co/admin/api/pages/3",
      "public_url": "http://helloworld.voog.co/blog",
    },
    "language": {
      "id": 1,
      "code": "en",
      "title": "ENG",
      "created_at": "2014-01-23T09:19:04.000Z",
      "updated_at": "2014-01-23T09:19:04.000Z",
      "url": "http://helloworld.voog.co/admin/api/languages/1"
    },
    "author": {
      "id": 1,
      "name": "John Smith",
      "url": "http://helloworld.voog.co/admin/api/people/1"
    },
    "seo": {
      "full_title": "Having sample news pieces? < My new site",
      "title_format": "<page_title> <separator> <site_title>",
      "score": 87,
      "metrics": [
        {
          "key": "title_length",
          "score": 75,
          "result": "warning"
        },
        {
          "key": "description_length",
          "score": 100,
          "result": "pass"
        }
      ]
    }
  }
]

Example response (anonymous request):

Status: 200 OK

[
  {
    "id": 2,
    "title": "How I wrote my first article",
    "path": "how-i-wrote-my-first-article",
    "description": "",
    "recaptcha": null,
    "public_comments_count": 0,
    "data": {},
    "created_at": "2014-01-23T09:22:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/articles/2",
    "public_url": "http://helloworld.voog.co/blog/how-i-wrote-my-first-article",
    "comments_url": "http://helloworld.voog.co/admin/api/articles/2/comments",
    "page": {
      "id": 3,
      "path": "blog",
      "title": "Blog",
      "public_url": "http://helloworld.voog.co/blog"
    },
    "language": {
      "id": 1,
      "code": "en",
      "title": "ENG"
    },
    "author": {
      "name": "John Smith"
    }
  }, {
    "id": 1,
    "title": "Having sample news pieces?",
    "path": "having-sample-news-pieces",
    "description": "",
    "recaptcha": null,
    "public_comments_count": 0,
    "data": {},
    "created_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/articles/1",
    "public_url": "http://helloworld.voog.co/blog/having-sample-news-pieces",
    "comments_url": "http://helloworld.voog.co/admin/api/articles/1/comments",
    "page": {
      "id": 3,
      "path": "blog",
      "title": "Blog",
      "public_url": "http://helloworld.voog.co/blog"
    },
    "language": {
      "id": 1,
      "code": "en",
      "title": "ENG"
    },
    "author": {
      "name": "John Smith"
    }
  }
]

Parameters

• per_page - elements per response (default: 50; maximum: 250).
• page - requested page (default: 1).
• page_id - articles parent page id (e.g. 1). Returns only articles for requested page.
• language_id - language id (e.g. 1). Returns only articles for requested language.
• language_code - language code (e.g. ?language_code=en). Returns only articles with requested language code.
• tag - tag label or labels (e.g. ?tag=tag1 or ?tag[]=tag1&tag[]=tag2). Returns articles tagged with requested tag.
• include_tags - includes list article tags (e.g. ?include_tags=true).
• include_details - includes body and excerpt attributes if present in request (e.g. ?include_details=true).
• include_seo - includes SEO-related output.

Filter attributes

Read more about filters.

• Object article attributes: id, page_id, language_id, title, path, excerpt, body, autosaved_title, autosaved_excerpt, autosaved_body, public_comments_count, comments_count, publishing, published_at, created_at, updated_at, published_at, created_by.
• Object page attributes: id, language_id, node_id, layout_id, title, path, content_type, keywords, description, hidden, publishing, privacy, created_at, updated_at, published_at.
• Object language attributes: id, code, title, position, default_language, created_at, updated_at.
• Object author attributes: id, email, firstname, lastname.
• Object tag attributes: id, language_id, name, created_at, updated_at.

Create a new article

POST /admin/api/articles

Example data:

{
  "page_id": 1,
  "autosaved_title": "Title of new article",
  "autosaved_excerpt": "Excerpt of new article",
  "autosaved_body": "Body of new article",
  "path": "my-new-article",
  "description": "My description",
  "publishing": false,
  "tag_names": ["tag1", "tag2"]
}

Example response:

Status: 201 Created

{
  "id": 3,
  "title": "My new article",
  "autosaved_title": "Title of new article",
  "path": "my-new-article",
  "description": "My description",
  "recaptcha": null,
  "comments_count": 0,
  "public_comments_count": 0,
  "publishing": false,
  "published": false,
  "data": {},
  "title_format": null,
  "title_separator": null,
  "created_at": "2014-01-23T09:22:04.000Z",
  "updated_at": "2014-01-23T09:22:04.000Z",
  "published_at": null,
  "url": "http://helloworld.voog.co/admin/api/articles/3",
  "public_url": "http://helloworld.voog.co/blog/my-new-article",
  "contents_url": "http://helloworld.voog.co/admin/api/articles/3/contents",
  "comments_url": "http://helloworld.voog.co/admin/api/articles/3/comments",
  "page": {
    "id": 3,
    "path": "blog",
    "title": "Blog",
    "content_type": "blog",
    "created_at": "2014-01-23T09:19:04.000Z",
    "updated_at": "2014-01-23T09:19:04.000Z",
    "published_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/3",
    "public_url": "http://helloworld.voog.co/blog",
  },
  "language": {
    "id": 1,
    "code": "en",
    "title": "ENG",
    "created_at": "2014-01-23T09:19:04.000Z",
    "updated_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/languages/1"
  },
  "author": {
    "id": 2,
    "name": "Api User",
    "url": "http://helloworld.voog.co/admin/api/people/2"
  },
  "seo": {
    "full_title": "My new article – My new site",
    "title_format": "<page_title> <separator> <site_title>",
    "score": 87,
    "metrics": [
      {
        "key": "title_length",
        "score": 75,
        "result": "warning"
      },
      {
        "key": "description_length",
        "score": 100,
        "result": "pass"
      }
    ]
  }
}

Parameters

Required parameters are:

• page_id - parent (blog)page id.
• autosaved_title - article (unpublished) title. The value is copied automatically to title field on publishing.

Optional parameters:

• path - url part under that should be unique under parent page (e.g. "my-new-article"). When empty then its automatically generate from title value on create. When there has already article with same path then number is automatically appended to path value (e.g. "my-new-article-3").
• autosaved_excerpt - article (unpublished) excerpt. The value is copied automatically to excerpt field on publishing.
• autosaved_body - article (unpublished) excerpt. The value is copied automatically to autosaved_body field on publishing.
• description - article description meta tag.
• image_id - id of the article descriptive image (commonly used for OG tags) - should be id of asset with image type (default: null).
• tag_names - array of tags related to article (e.g. ["tag1", "tag2"]).
• recaptcha - Google reCAPTCHA v3 spam protection. Accepted values: null, true, false (default: null - controlled by site subscription (means true by default)).
• data - key/value based custom hash store. (NB! Keys with prefixes internal_ are protected and read only.)
• publishing - publish changes automatically. If true, every article update is published automatically. (Default: false).
• published - If false, the article is hidden. If true and publishing is false, the article is in draft state. If true and publishing is true, the article is published.
• robots_header - HTTP X-Robots-Tag header value (read more). When set then HTTP header X-Robots-Tag is added to current page response. Example values: noindex or noindex, nofollow (default: null).
• title_format - default title format for the article page title tag. Defaults to site title_format value. Supported values and their corresponding patterns:
  • page_site - <page_title> <separator> <site_title>
  • site_page - <site_title> <separator> <page_title>
  • page - <page_title>
  • site - <site_title>
• title_separator - default title format separator for the article page title tag. Defaults to site title_separator value.
• include_seo - includes SEO-related output.

NB! On create values of title, excerpt and body are auto filled with values of corresponds autosaved_ values regardless of publishing flag.

NB! On create the article is not published unless publishing flag is turned on.

Get data for a single article

GET /admin/api/articles/1

Get detailed data for single article (includes also excerpt, body and tag_names).

This endpoint also allows anonymous access which returns some important fields about article.

Example request:

GET http://helloworld.voog.co/admin/api/articles/1

Example response (authenticated request):

Status: 200 OK

{
  "id": 1,
  "title": "Having sample news pieces?",
  "autosaved_title": "Having sample news pieces?",
  "path": "having-sample-news-pieces",
  "description": "",
  "recaptcha": null,
  "comments_count": 0,
  "public_comments_count": 0,
  "publishing": true,
  "published": true,
  "data": {},
  "title_format": null,
  "title_separator": null,
  "created_at": "2014-01-23T09:19:04.000Z",
  "updated_at": "2014-01-23T09:19:04.000Z",
  "published_at": "2014-01-23T09:19:04.000Z",
  "url": "http://helloworld.voog.co/admin/api/articles/1",
  "public_url": "http://helloworld.voog.co/blog/having-sample-news-pieces",
  "contents_url": "http://helloworld.voog.co/admin/api/articles/1/contents",
  "comments_url": "http://helloworld.voog.co/admin/api/articles/1/comments",
  "page": {
    "id": 3,
    "title": "Blog",
    "content_type": "blog",
    "created_at": "2014-01-23T09:19:04.000Z",
    "updated_at": "2014-01-23T09:19:04.000Z",
    "published_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/3"
  },
  "language": {
    "id": 1,
    "code": "en",
    "title": "ENG",
    "created_at": "2014-01-23T09:19:04.000Z",
    "updated_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/languages/1"
  },
  "author": {
    "id": 1,
    "name": "John Smith",
    "url": "http://helloworld.voog.co/admin/api/people/1"
  },
  "autosaved_title": "Having sample news pieces?",
  "excerpt": "Post news of any subject your audience would appreciate.",
  "autosaved_excerpt": "Post news of any subject your audience would appreciate.",
  "body": "The above is excerpt of the article. It appears in the blog post listing. This here is the body of the post. This only appears here, on the post page.",
  "autosaved_body": "The above is excerpt of the article. It appears in the blog post listing. This here is the body of the post. This only appears here, on the post page.",
  "seo": {
    "full_title": "Having sample news pieces? – My new site",
    "title_format": "<page_title> <separator> <site_title>",
    "score": 87,
    "metrics": [
      {
        "key": "title_length",
        "score": 75,
        "result": "warning"
      },
      {
        "key": "description_length",
        "score": 100,
        "result": "pass"
      }
    ]
  },
  "image": {
    "id": 1,
    "content_type": "image/jpeg",
    "width": 1024,
    "height": 768,
    "url": "http://helloworld.voog.co/admin/api/assets/1",
    "public_url": "http://media.voog.com/0000/0000/0001/photos/Chrysanthemum.jpg",
    "sizes": [
      {
        "content_type": "image/jpeg",
        "width": 600,
        "height": 450,
        "url": "http://media.voog.com/0000/0000/0001/photos/Chrysanthemum_block.jpg"
      },
      {
        "content_type": "image/jpeg",
        "width": 1024,
        "height": 768,
        "url": "http://media.voog.com/0000/0000/0001/photos/Chrysanthemum.jpg"
      }
    ]
  },
  "tag_names": []
}

Example response (anonymous request):

Status: 200 OK

{
  "id": 1,
  "title": "Having sample news pieces?",
  "autosaved_title": "Having sample news pieces?",
  "path": "having-sample-news-pieces",
  "description": "",
  "recaptcha": null,
  "public_comments_count": 0,
  "data": {},
  "created_at": "2014-01-23T09:19:04.000Z",
  "url": "http://helloworld.voog.co/admin/api/articles/1",
  "public_url": "http://helloworld.voog.co/blog/having-sample-news-pieces",
  "comments_url": "http://helloworld.voog.co/admin/api/articles/1/comments",
  "page": {
    "id": 3,
    "title": "Blog",
    "url": "http://helloworld.voog.co/admin/api/pages/3"
  },
  "language": {
    "id": 1,
    "code": "en",
    "title": "ENG"
  },
  "author": {
    "name": "John Smith"
  },
  "excerpt": "Post news of any subject your audience would appreciate.",
  "body": "The above is excerpt of the article. It appears in the blog post listing. This here is the body of the post. This only appears here, on the post page.",
  "image": {
    "content_type": "image/jpeg",
    "width": 1024,
    "height": 768,
    "public_url": "http://media.voog.com/0000/0000/0001/photos/Chrysanthemum.jpg",
    "sizes": [
      {
        "content_type": "image/jpeg",
        "width": 600,
        "height": 450,
        "url": "http://media.voog.com/0000/0000/0001/photos/Chrysanthemum_block.jpg"
      },
      {
        "content_type": "image/jpeg",
        "width": 1024,
        "height": 768,
        "url": "http://media.voog.com/0000/0000/0001/photos/Chrysanthemum.jpg"
      }
    ]
  },
  "tag_names": []
}

Parameters

• include_seo - includes SEO-related output.

Update attributes of a single article

PUT /admin/api/articles/1

This request updates the article with provided attributes. It replaces data attribute with new key set if data attribute is present in request.

PATCH /admin/api/articles/1

This request updates the article with provided attributes. It merges provided keys to data attribute if data attribute is present in request.

Example request:

PUT http://helloworld.voog.co/admin/api/articles/3

Example data:

{
  "title": "Updated title of article 1",
  "description": "Updated description",
  "title_format": "page",
  "created_at": "01.01.2014",
  "created_by": 1,
  "tag_names": ["tag2", "tag1"],
  "published": true
}

Example response:

Status: 200 OK

{
  "id": 3,
  "title": "Updated title of article 1",
  "autosaved_title": "Updated title of article 1",
  "path": "my-new-article",
  "description": "Updated description",
  "recaptcha": null,
  "comments_count": 0,
  "public_comments_count": 0,
  "publishing": true,
  "published": true,
  "data": {},
  "title_format": "page",
  "title_separator": null,
  "created_at": "2014-01-01T00:00:00.000Z",
  "updated_at": "2014-01-23T10:03:04.000Z",
  "published_at": "2014-01-23T10:03:04.000Z",
  "url": "http://helloworld.voog.co/admin/api/articles/3",
  "public_url": "http://helloworld.voog.co/blog/my-new-article",
  "contents_url": "http://helloworld.voog.co/admin/api/articles/3/contents",
  "comments_url": "http://helloworld.voog.co/admin/api/articles/3/comments",
  "page": {
    "id": 3,
    "title": "Blog",
    "content_type": "blog",
    "created_at": "2014-01-23T09:19:04.000Z",
    "updated_at": "2014-01-23T09:19:04.000Z",
    "published_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/3"
  },
  "language": {
    "id": 1,
    "code": "en",
    "title": "ENG",
    "created_at": "2014-01-23T09:19:04.000Z",
    "updated_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/languages/1"
  },
  "author": {
    "id": 1,
    "name": "John Smith",
    "url": "http://helloworld.voog.co/admin/api/people/1"
  },
  "seo": {
    "full_title": "Updated title of article 1",
    "title_format": "<page_title>",
    "score": 87,
    "metrics": [
      {
        "key": "title_length",
        "score": 75,
        "result": "warning"
      },
      {
        "key": "description_length",
        "score": 100,
        "result": "pass"
      }
    ]
  }
}

Parameters

Optional parameters:

• autosaved_title - article (unpublished) title. The value is copied automatically to title field on publishing.
• path - url part under that should be unique under parent page (e.g. "my-new-article"). When there has already article with same path then number is automatically appended to path value (e.g. "my-new-article-3").
• autosaved_excerpt - article (unpublished) excerpt. The value is copied automatically to excerpt field on publishing.
• autosaved_body - article (unpublished) excerpt. The value is copied automatically to autosaved_body field on publishing.
• description - article description meta tag.
• image_id - id of the article descriptive image (commonly used for OG tags) - should be id of asset with image type (default: null).
• created_at - article creation date in format "dd.mm.yyyy" (e.g. "01.30.2014"). Allows to change article creation date.
• created_by - author of the article (site person id e.g. 2). Allows to override the original creator.
• tag_names - array of tags related to article (e.g. ["tag1", "tag2"]). When provided then replaces current tags set with new one.
• data - key/value based custom hash store. (NB! Keys with prefixes internal_ are protected and read only.)
• publishing - publish changes automatically. If true, every article update is published automatically.
• published - If false then unpublish the article and force publishing to false. If true and publishing is false, set the article to draft state. If true and publishing is true, publish the article.
• robots_header - HTTP X-Robots-Tag header value (read more). When set then HTTP header X-Robots-Tag is added to current page response. Example values: noindex or noindex, nofollow (default: null).
• title_format - default title format for the article page title tag. Defaults to site title_format value. Supported values and their corresponding patterns:
  • page_site - <page_title> <separator> <site_title>
  • site_page - <site_title> <separator> <page_title>
  • page - <page_title>
  • site - <site_title>
• title_separator - default title format separator for the article page title tag. Defaults to site title_separator value.
• include_seo - includes SEO-related output.

Update data field of an article

PUT /admin/api/articles/1/data/custom_field

Updates or adds a new key to article data keyset.

Example request:

PUT http://helloworld.voog.co/admin/api/articles/1/data/my_new_key

Example data:

{
  "value": ["foo", "bar"]
}

Example response:

Status: 200 OK

{
  "id": 3,
  "title": "Updated title of article 1",
  "autosaved_title": "Updated title of article 1",
  "path": "my-new-article",
  "description": "Updated description",
  "recaptcha": null,
  "comments_count": 0,
  "public_comments_count": 0,
  "publishing": true,
  "published": true,
  "data": {
    "my_new_key": ["foo", "bar"]
  },
  "title_format": "page",
  "title_separator": null,
  "created_at": "2014-01-01T00:00:00.000Z",
  "updated_at": "2014-01-23T10:03:04.000Z",
  "published_at": "2014-01-23T10:17:04.000Z",
  "url": "http://helloworld.voog.co/admin/api/articles/3",
  "public_url": "http://helloworld.voog.co/blog/my-new-article",
  "contents_url": "http://helloworld.voog.co/admin/api/articles/3/contents",
  "comments_url": "http://helloworld.voog.co/admin/api/articles/3/comments",
  "page": {
    "id": 3,
    "title": "Blog",
    "content_type": "blog",
    "created_at": "2014-01-23T09:19:04.000Z",
    "updated_at": "2014-01-23T09:19:04.000Z",
    "published_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/3"
  },
  "language": {
    "id": 1,
    "code": "en",
    "title": "ENG",
    "created_at": "2014-01-23T09:19:04.000Z",
    "updated_at": "2014-01-23T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/languages/1"
  },
  "author": {
    "id": 1,
    "name": "John Smith",
    "url": "http://helloworld.voog.co/admin/api/people/1"
  }
}

Remove a custom field from an article

DELETE /admin/api/articles/1/data/custom_field

Example request:

DELETE http://helloworld.voog.co/admin/api/articles/1/data/custom_field

Example response:

Status: 204 No Content

Remove an article

DELETE /admin/api/articles/1

This request deletes the article from the database.

Example request:

DELETE http://helloworld.voog.co/admin/api/articles/1

Example response:

Status: 204 No Content