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.

Pricing

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: https://talk.hyvor.com/api/data/v1

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

Endpoints

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:

Objects Definitions

All dates are in UNIX timestamp (seconds) format.

Comment

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,
}

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
    },
}

User

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
}

Filtering

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:

• key
• operator
• value

Operator

• = - equals
• != - not equal
• > - greater than
• < - less than
• >= - greater than or equals
• <= - less than or equals

Value

• null
• bool: true or false
• string: 'hello' or hello
  • Strings without quotes should match [a-zA-Z_][a-zA-Z0-9_-]+ and cannot be true, false, or null.
• numbers: 250, -250, 2.5

Date Values

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

• '2022-01-01'
• 'yesterday'
• 'first day of this year'
• 'last day of next month'
• '+1 day'
• '-1 week'
• 'next Thursday'
• 1639655890 (UNIX Timestamp)

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.

• & - AND
• | - OR

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

Supported Keys for Filtering

Sorting

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.

Examples:

• created_at : Sort by created time in descending order
• created_at ASC : Sort by created time in ascending order
• is_featured DESC, created_at ASC : Sort by featured status in descending order, then by created time in ascending order