Developers

Articles

Summary of article endpoints

Related endpoints:

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",
    "path": "how-i-wrote-my-first-article",
    "description": "",
    "comments_count": 0,
    "public_comments_count": 0,
    "publishing": true,
    "published": true,
    "data": {},
    "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"
    }
  }, {
    "id": 1,
    "title": "Having sample news pieces?",
    "path": "having-sample-news-pieces",
    "description": "",
    "comments_count": 0,
    "public_comments_count": 0,
    "publishing": true,
    "published": true,
    "data": {},
    "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"
    }
  }
]

Example response (anonymous request):

Status: 200 OK
[
  {
    "id": 2,
    "title": "How I wrote my first article",
    "path": "how-i-wrote-my-first-article",
    "description": "",
    "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": "",
    "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).

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.

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": "Title of new article",
  "path": "my-new-article",
  "description": "My description",
  "comments_count": 0,
  "public_comments_count": 0,
  "publishing": false,
  "published": false,
  "data": {},
  "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"
  }
}

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"]).
  • data - key/value based custom hash store. (NB! Keys with prefixes internal_ are protected and read only.)
  • publishing - publish changes automatically. If turned on then every article update is published automatically. (Default: false).

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?",
  "path": "having-sample-news-pieces",
  "description": "",
  "comments_count": 0,
  "public_comments_count": 0,
  "publishing": true,
  "published": true,
  "data": {},
  "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.",
  "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?",
  "path": "having-sample-news-pieces",
  "description": "",
  "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": []
}

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",
  "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",
  "path": "my-new-article",
  "description": "Updated description",
  "comments_count": 0,
  "public_comments_count": 0,
  "publishing": true,
  "published": true,
  "data": {},
  "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"
  }
}

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 turned on then every article update is published automatically. When true value is provided then forces publishing.
  • published - when false then unpublish the article from public and forces publishing flag to false. When true then publish the article.

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",
  "path": "my-new-article",
  "description": "Updated description",
  "comments_count": 0,
  "public_comments_count": 0,
  "publishing": true,
  "published": true,
  "data": {
    "my_new_key": ["foo", "bar"]
  },
  "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