The Isso API uses HTTP and JSON as primary communication protocol.

JSON format

When querying the API you either get a regular HTTP error, an object or list of objects representing the comment. Here’s an example JSON returned from Isso:

    "id": 1,
    "parent": null,
    "text": "<p>Hello, World!</p>\n",
    "mode": 1,
    "hash": "4505c1eeda98",
    "author": null,
    "website": null,
    "created": 1387321261.572392,
    "modified": null,
    "likes": 3,
    "dislikes": 0
id :
comment id (unique per website).
parent :
parent id reference, may be null.
text :
required, comment written in Markdown.
mode :
  • 1 – accepted
  • 2 – in moderation queue
  • 4 – deleted, but referenced.
hash :
user identication, used to generate identicons. PBKDF2 from email or IP address (fallback).
author :
author’s name, may be null.
website :
author’s website, may be null.
likes :
upvote count, defaults to 0.
dislikes :
downvote count, defaults to 0.
created :
time in seconds since UNIX time.
modified :
last modification since UNIX time, may be null.

List comments

List all publicly visible comments for thread uri:

GET /?uri=%2Fhello-world%2F
uri :
URI to fetch comments for, required.
plain :
pass plain=1 to get the raw comment text, defaults to 0.

Create comment

To create a new comment, you need to issue a POST request to /new and add the current URI (so the server can check if the location actually exists).

$ curl -vX POST http://isso/new?uri=%2F -d '{"text": "Hello, World!"}' -H "Content-Type: application/json"
< HTTP/1.1 201 CREATED
< Set-Cookie: 1=...; Expires=Wed, 18-Dec-2013 12:57:20 GMT; Max-Age=900; Path=/
    "author": null,
    "created": 1387370540.733824,
    "dislikes": 0,
    "email": null,
    "hash": "6dcdbfb4f00d",
    "id": 1,
    "likes": 0,
    "mode": 1,
    "modified": null,
    "parent": null,
    "text": "<p>Hello, World!</p>\n",
    "website": null

The payload must be valid JSON. To prevent CSRF attacks, you must set the Content-Type to application/json or omit the header completely.

The server issues a cookie per new comment which acts as authentication token to modify or delete your own comment. The token is cryptographically signed and expires automatically after 900 seconds by default.

The following keys can be used to POST a new comment, all other fields are dropped or replaced with values from the server:

text : String
Actual comment, at least three characters long, required.
author : String
Comment author, optional.
website : String
Commenter’s website (currently no field available in the client JS though), optional.
email : String
Commenter’s email address (can be any arbitrary string though) used to generate the identicon. Limited to 254 characters (RFC specification), optional.
parent : Integer
Reference to parent comment, optional.

Edit comment

When your authentication token is not yet expired, you can issue a PUT request to update text, author and website. After an update, you get an updated authentication token and the comment as JSON:

$ curl -X PUT http://isso/id/1 -d "..." -H "Content-Type: application/json"

Delete comment

You can delete your own comments when your authentication token (= cookie) is not yet expired:

$ curl -X DELETE http://isso/id/1 -H "Content-Type: application/json"

Returns either null or a comment with an empty text value when the comment is still referenced by other comments.

Get comment count

Counts all publicly visible comments for thread uri:

GET /count?uri=%2Fhello-world%2F
uri :
URI to count comments for, required.

returns an integer