Data API

Data API gives access to public data of your website, such as comments, pages, and users. All endpoints use the HTTP GET method, and returns a JSON response.

Rate Limiting

The Data API is designed keeping scaling in mind. As the Data API can be used in the front-end to get comment counts or render a UI like "most recent comments", the API is built to scale with your traffic. We use caching extensively to ensure that the API is fast and scalable. Therefore, the Data API does not impose any rate limits. You can safely use it to fetch data from your front-ends, even you have a high traffic website.


At this moment, the Data API is free. We'll introduce a pricing model in the future as explained below:

"A Data API request that misses cache will be recorded as a "pageview". It will be added to your monthly pageview count. Caching timeframe is currently 30 seconds. As an example, if you make 1,000 calls within 30 seconds to the same endpoint with the same request data, it will only count one pageview."

Server-side vs Client-side

There are two ways to access the API.

Server-side: You can access the Data API from your servers. This is secured by your API key. You can find your data API key in the Console. In the Data API request, add your API key as the api_key query parameter along with other parameters.

Client-side: You can access the Data API from your front-end using Javascript. This is secured by the HTTP Referer header. The domains you access the API should be added to allowed domains in the Console. Hyvor Talk will reject requests from other domains. To enable client-side access, use the API public access settings in the Console. No API key is required for client-side access.

Turning on public access will disable the API key requirement.

Accessing the API

Base URL:

All endpoints require the website_id query parameter. You can find your website ID in the Console.


There are 3 endpoints:

  1. /comments - Returns an array of Comment objects
  2. /pages - Returns an array of Page objects
  3. /users - Returns an array of User objects

Query Parameters

All endpoints have the following query parameters:

Parameter Type Description Default
website_id integer Your website ID Required
api_key string API key for server-side access
limit integer Limit results (min: 1, max: 50) 10
offset integer Skip results (for pagination) 0
filter string See Filtering. null
sort string See Sorting. null

Objects Definitions

All dates are in UNIX timestamp (seconds) format.


interface Comment {
    id: number,

    // for nested comments
    // first id is the direct parent
    parent_ids: number[],
    depth: number,

    created_at: number,
    body_json: string, // ProseMirror JSON
    body_html: string,

    is_featured: boolean,
    is_loved: boolean,
    is_edited: boolean,

    upvotes: number,
    downvotes: number,

    user: User,
    page: Page,


interface Page {
    id: number,
    created_at: number,
    identifier: string, // page-id
    url: string,
    title: string,
    comments_count: number,
    reactions: {
        superb: number,
        love: number,
        wow: number,
        sad: number,
        laugh: number,
        angry: number
    ratings: {
        average: number,
        count: number


interface User {
    htid: string, // "hyvor_10" or "sso_10"
    name: string,
    username: string | null,
    picture_url: string | null,
    bio: string | null,
    location: string | null,
    website_url: string | null,
    created_at: number | null,
    last_commented_at: number | null,
    comments_count: number,
    badge_ids: number[],

In the Comment object, the user key is a User object. For guest comments, the user object can take the following form:

// guest user
interface User {
    htid: null,
    name: string,
    picture_url: string | null


We use FilterQ expressions to allow advanced filtering. You can filter comments, pages, and users using the filter query parameter.

Example filter:

(created_at > '2022-01-01' & created_at < '2022-12-31') | is_featured=true

A FilterQ expression consists of one or more conditions. A condition has three parts:



Date Values

Some keys accept date strings. Here are some valid date values:

For example: You may use created_at>'-7 days' to get data created in the last 7 days.

Logical Operators

You can use Logical Operators to combine multiple conditions.

Please see the FilterQ Expressions documentation if you need more details.

Supported Keys for Filtering

Endpoint Key Supported Operators Value Type Description
/comments id all integer
parent_id all integer Direct parent comment ID
created_at all date See Date
page_id all integer
is_featured =, != boolean Featured (pinned)
is_loved =, != boolean Loved by mods
/pages id all integer
identifier all string page-id
created_at all date Created time
last_commented_at all date Time of last comment
comments_count all integer
reactions_count all integer
/users created_at all date Created time, usually the time of first comment
last_commented_at all date Time of last comment
comments_count all integer


Set the sort query parameter to sort the results. Here's a list of supported sort values. You can combine them as comma-separated-values, which will then be executed in its order, similar to ORDER BY in SQL.

Endpoint Default Sort Description
/comments created_at DESC created_at comment publish time
id comment ID
upvotes number of upvotes
/pages id DESC id page ID
last_commented_at last comment time
comments_count number of comments
reactions_count number of reactions
/users created_at DESC created_at user created time
last_commented_at last comment time
comments_count number of comments