A comment is a reader's response to an article in a blog. They appear on the article page in chronological order, typically after the article body.

Just as a blog can have any number of articles, an article can have any number of comments. Blog comments are a target for spammers, so haravan's blogs make use of a spam detection system to identify comments that are likely to be spam. Shop owners can mark comments as spam and not spam, which not only hides or unhides them from the readers' view, but also trains the haravan spam detection system.

What you can do with Comment?

The haravan API lets you do the following with the Comment resource. More detailed versions of these general actions may be available:

Comment Properties

article_id
{ "article_id" : 134645308 }

A unique numeric identifier for the article to which the comment belongs.

author
{ "author" : "Soleone" }

The name of the author of the comment.

blog_id
{ "blog_id" : 241253187 }

A unique numeric identifier for the blog containing the article that the comment belongs to.

body
{ "body" : "I really _like_ this." }

The basic textile markup of a comment.

body_html
{ "body_html" : "I really _like_ this."}

The text of the comment, complete with HTML markup.

created_at
{ "created_at" : "2012-08-24T14:01:46-04:00" }

The date and time when the comment was created. The API returns this value in ISO 8601 format. 

email
{ "email" : "sole@one.de" }

The email address of the author of the comment. 

id
{ "id" : 653537639 }

A unique numeric identifier for the comment.

ip
{ "ip" : "127.0.0.1" }

The IP address from which the comment was posted.

published_at
{ "published_at" : "2012-08-24T14:02:00-04:00" }

The date and time when the comment was published. In the case of comments, this is the date and time when the comment was created, meaning that it has the same value as created_at. The API returns this value in ISO 8601 format.

status
{ "status" : "removed" }


The status of the comment. The possible values are:

  • unapproved (default): The comment is awaiting moderation by the shop owner and is not visible to the readers of the blog.
  • published: The comment has been approved (if the blog requires comments to be moderated) and is visible to readers of the blog.
  • spam: The comment has been marked as spam by the shop owner and is not visible to readers of the blog.
  • removed: The comment has been removed from the article.


updated_at
{ "updated_at" : "null" }

The date and time when the comment was last modified. When the comment is first created, this is the date and time when the comment was created, meaning that it has the same value as created_at. If the blog requires comments to be approved, this value is updated to the date and time the comment was approved upon approval. The API returns this value in ISO 8601 format.

user_agent
{ "user_agent" : "Mozilla/5.0" }

The user agent string provided by the software (usually a browser) used to create the comment.


Endpoints

GET/web/comments.json
Get a list of all comments for an article
LimitAmount of results
(default: 50) (maximum: 250)
pagePage to show
(default: 1)
since_idRestrict results to after the specified ID
created_at_minShow comments created after date (format: 2008-12-31 03:00)
created_at_maxShow comments created before date (format: 2008-12-31 03:00)
updated_at_minShow comments last updated after date (format: 2008-12-31 03:00)
updated_at_maxShow comments last updated before date (format: 2008-12-31 03:00)
published_at_minShow comments published after date (format: 2008-12-31 03:00)
published_at_maxShow comments published before date (format: 2008-12-31 03:00)
fieldscomma-separated list of fields to include in the response
published_status
  • published - Show only published comments
  • unpublished - Show only unpublished comments
  • any - Show all comments (default)
status
  • pending - All pending comments
  • published - Show only published comments
  • unapproved - Show only unapproved comments

Get all the comments for a certain article of a blog

GET /web/comments.json?article_id=134645308&blog_id=241253187

Response:

HTTP/1.1 200 OK
{
  "comments": [
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "sole@one.de",
      "id": 653537639,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "unapproved",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    },
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "sole@one.de",
      "id": 118373535,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "published",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    }
  ]
}

Get all the comments for all the articles of a certain blog

GET /web/comments.json?blog_id=241253187

Response:

HTTP/1.1 200 OK
{
  "comments": [
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "sole@one.de",
      "id": 653537639,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "unapproved",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    },
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "sole@one.de",
      "id": 118373535,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "published",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    }
  ]
}

Get all the comments for this shop

GET /web/comments.json

Response:

HTTP/1.1 200 OK
{
  "comments": [
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "sole@one.de",
      "id": 653537639,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "unapproved",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    },
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "sole@one.de",
      "id": 118373535,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "published",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    }
  ]
}

Get all comments after the specified ID

GET /web/comments.json?since_id=118373535

Response:

HTTP/1.1 200 OK
{
  "comments": [
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "sole@one.de",
      "id": 653537639,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "unapproved",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    }
  ]
}
GET/web/comments/count.json
Get a count of all comments for an article
created_at_minCount comments created after date (format: 2008-12-31 03:00)
created_at_maxCount comments created before date (format: 2008-12-31 03:00)
updated_at_minCount comments last updated after date (format: 2008-12-31 03:00)
updated_at_maxCount comments last updated before date (format: 2008-12-31 03:00)
published_at_minCount comments published after date (format: 2008-12-31 03:00)
published_at_maxCount comments published before date (format: 2008-12-31 03:00)
published_status
  • published - Count only published comments
  • unpublished - Count only unpublished comments
  • any - Count all comments (default)
status
  • pending - All pending comments
  • published - Count only published comments
  • unapproved - Count only unapproved comments

Count all comments for a certain article of a blog

GET /web/comments/count.json?article_id=134645308&blog_id=241253187

Response:

HTTP/1.1 200 OK
{
  "count": 2
}

Get a count of all the comments for all the articles of a certain blog

GET /web/comments/count.json?blog_id=241253187

Response:

HTTP/1.1 200 OK
{
  "count": 2
}

Get a count of all the comments for this shop

GET /web/comments/count.json

Response:

HTTP/1.1 200 OK
{
  "count": 2
}

GET/web/comments/118373535.json

Get a single comment by its ID
fields

comma-separated list of fields to include in the response

Get a single comment

GET /web/comments/#{id}.json

Response:

HTTP/1.1 200 OK
{
  "comment": {
    "article_id": 134645308,
    "author": "Soleone",
    "blog_id": 241253187,
    "body": "Hi author, I really _like_ what you're doing there.",
    "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
    "created_at": "2015-03-28T13:26:28-04:00",
    "email": "sole@one.de",
    "id": 118373535,
    "ip": "127.0.0.1",
    "published_at": null,
    "status": "published",
    "updated_at": "2015-03-28T13:26:28-04:00",
    "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
  }
}


POST/web/comments.json

Create a new comment for an article

Create a new comment with basic textile markup for a certain article of a blog

POST /web/comments.json
{
  "comment": {
    "body": "I like comments\nAnd I like posting them *RESTfully*.",
    "author": "Your name",
    "email": "your@email.com",
    "ip": "107.20.160.121",
    "blog_id": 241253187,
    "article_id": 134645308
  }
}

Response:

HTTP/1.1 201 Created
{
  "comment": {
    "article_id": 134645308,
    "author": "Your name",
    "blog_id": 241253187,
    "body": "I like comments\nAnd I like posting them *RESTfully*.",
    "body_html": "<p>I like comments<br \/>\nAnd I like posting them <strong>RESTfully<\/strong>.<\/p>",
    "created_at": "2015-03-28T13:27:26-04:00",
    "email": "your@email.com",
    "id": 757536352,
    "ip": "107.20.160.121",
    "published_at": "2015-03-28T13:27:26-04:00",
    "status": "pending",
    "updated_at": "2015-03-28T13:27:26-04:00",
    "user_agent": null
  }
}

Trying to create a comment without a body, author, and email will return an error

POST /web/comments.json
{
  "comment": {
    "article_id": 134645308
  }
}

Response:

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "author": [
      "can't be blank"
    ],
    "body": [
      "can't be blank"
    ],
    "email": [
      "is invalid"
    ]
  }
}


PUT/web/comments/118373535.json

Update a comment of an article within a blog

Update an existing comment body

PUT /web/comments/#{id}.json
{
  "comment": {
    "id": 118373535,
    "body": "You can even update through a web service.",
    "author": "Your new name",
    "email": "your@updated-email.com",
    "published_at": "2015-03-28T17:27:28+00:00"
  }
}

Response:

HTTP/1.1 200 OK
{
  "comment": {
    "article_id": 134645308,
    "author": "Your new name",
    "blog_id": 241253187,
    "body": "You can even update through a web service.",
    "body_html": "<p>You can even update through a web service.<\/p>",
    "created_at": "2015-03-28T13:26:28-04:00",
    "email": "your@updated-email.com",
    "id": 118373535,
    "ip": "127.0.0.1",
    "published_at": "2015-03-28T13:27:28-04:00",
    "status": "published",
    "updated_at": "2015-03-28T13:27:29-04:00",
    "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
  }
}


POST/web/comments/653537639/spam.json

Mark a comment as spam

Mark a comment as spam, helping to train our spam detection as well as remove the comment sometime soon

POST /web/comments/#{id}/spam.json
{}

Response:

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "sole@one.de",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:28-04:00",
  "status": "spam",
  "updated_at": "2015-03-28T13:27:28-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}


POST/web/comments/653537639/not_spam.json

Mark a comment as not spam

Mark a comment as not spam, restoring a comment marked as spam back to published

POST /web/comments/#{id}/not_spam.json
{}

Response:

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "sole@one.de",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:28-04:00",
  "status": "published",
  "updated_at": "2015-03-28T13:27:28-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}


POST/web/comments/653537639/approve.json

Approve a comment

Approve a comment that is currently pending unapproved so that it will be published on the site

POST /web/comments/#{id}/approve.json
{}

Response:

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "sole@one.de",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:26-04:00",
  "status": "published",
  "updated_at": "2015-03-28T13:27:26-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}


POST/web/comments/653537639/remove.json

Remove a comment

Remove a comment

POST /web/comments/#{id}/remove.json
{}

Response:

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "sole@one.de",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:28-04:00",
  "status": "removed",
  "updated_at": "2015-03-28T13:27:28-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}


POST/web/comments/653537639/restore.json

Restore a Comment

Restore a Comment

POST /web/comments/#{id}/restore.json
{}

Response:

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "sole@one.de",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:28-04:00",
  "status": "published",
  "updated_at": "2015-03-28T13:27:28-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}