ezkomment REST API

If you feel that customising with templates is not enough for your use case, or you do not want to use plain HTML, or you want to integrate directly to your existing frontend, or you want to use custom Markdown flavours, you can use the ezkomment REST API to fetch and post comments directly for any ezkomment pages.

This documentation is for the API endpoints of version 1.x.x, under the following path

https://ezkomment.joulev.dev/api/v1

Content Type

All requests must be JSON (use Content-Type: application/json header), and all responses (including errors) will be JSON, unless specified otherwise.

Errors

If any errors are thrown, the response is in the following format (represented as TypeScript type), with a non-200 status code:

interface Response {
  error: string;
}

/comments/:siteId/:pageId

Endpoint to handle comments for any ezkomment page. To retrieve the siteId and pageId parameters, you can visit the site settings and the page settings page respectively.

Authentication

This endpoint is public, hence authentication is not required.

GET /comments/:siteId/:pageId

Fetch the comments for a particular page.

Body

Not applicable.

Response

If siteId and pageId are valid and correspond to an actual ezkomment page, the status code will be 200 with the JSON in the following format:

interface Response {
  message: string;
  data: {
    /** RAW comment content */
    text: string;
    /** Comment author, where null indicates Anonymous author */
    author: string | null;
    /** Timestamp of the comment, as milliseconds since Unix epoch */
    date: number;
    /** There may be more metadata, however they are not under semver so do not use them */
  }[];
}

Note that the comment content is served raw without any post-processing or sanitising, therefore when you render it please take XSS protection into account.

POST /comments/:siteId/:pageId

Post a new comment for a particular page. Depending on the auto-approve config of the page, the comment may be visible in the comment section immediately, or it may require you to manually approve it in the ezkomment dashboard.

Body

JSON in the following format:

interface Body {
  author: string | null;
  text: string;
}

Response

If siteId and pageId are valid and correspond to an actual ezkomment page, the status code will be 200 with the JSON in the following format:

interface Response {
  message: string;
  data: {
    /** RAW comment content */
    text: string;
    /** Comment author, where null indicates Anonymous author */
    author: string | null;
    /** Timestamp of the comment, as milliseconds since Unix epoch */
    date: number;
    /** There may be more metadata, however they are not under semver so do not use them */
  };
}

Example

POST https://ezkomment.joulev.dev/api/v1/comments/:siteId/:pageId
Content-Type: application/json

{
  "author": null,
  "text": "Test from API"
}