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.
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."
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.
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.
There are 3 endpoints:
/comments
- Returns an array of Comment objects/pages
- Returns an array of Page objects/users
- Returns an array of User objectsAll 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 |
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:
key
operator
value
=
- equals!=
- not equal>
- greater than<
- less than>=
- greater than or equals<=
- less than or equalsnull
true
or false
'hello'
or hello
[a-zA-Z_][a-zA-Z0-9_-]+
and cannot be true
, false
, or null
.250
, -250
, 2.5
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.
You can use Logical Operators to combine multiple conditions.
&
- AND|
- ORPlease see the FilterQ Expressions documentation if you need more details.
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 | |||
is_featured |
||||
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 |
Examples:
created_at
: Sort by created time in descending ordercreated_at ASC
: Sort by created time in ascending orderis_featured DESC, created_at ASC
: Sort by featured status in descending order, then by created time in ascending order