API (Beta)
API is currently in open beta. Contact us via live chat or at [email protected] for any questions.
You can use the Hyvor Talk API to access data on your website.
Accessing the API
There are two ways to access the API.
- Server-side: Using an API key
- Client-side (Javascript): The domain you access the API should be whitelisted. You can only access public data with this method. And, you should not use the API key here.
You can generate an API key or turn on public access from the API & Webhooks section in the console. All endpoints support both GET
and POST
HTTP methods (GET
is faster. POST
is more secure.)
Common Request Parameters
All endpoints require these two parameters.
Parameter | Value |
---|---|
website_id |
Your website ID |
api_key |
Your API Key (Only for server-side access) |
Endpoints that return an array of objects (Ex: Pages) support these parameters.
Parameter | Value | Default |
---|---|---|
limit |
Number of objects per response (Max 250) | 10 |
offset |
Use offset if you want to load more pages after the first request. For example, first, you get the first ten pages, then make a request with offset 10 to get the next 10 pages. | 0 |
filter |
Comma-separated keys to filters the results.* | null |
*You may not need all the data provided from the API. To reduce bandwidth, you can filter the results by keys. For example, if you want to get the only identifier
and comments_count
from the response of pages endpoint, set filter
to identifier, comments_count
.
Filtered results:
[
{
"identifier": "some-identifier",
"comments_count": 24
},
{
"identifier": "some-another-identifier",
"comments_count": 16
}
]
Responses
All endpoints return a JSON response in the following format.
Success Response
{
"status": true,
"data": {}
}
data
can be an object or an array of objects.
Error Response
{
"status": false,
"error": "Error Description"
}
Endpoints
Base URL: https://talk.hyvor.com/api/v1/
Endpoint | Response | Client-side Access |
---|---|---|
pages |
An array of page objects | Yes |
comments |
An array of comment objects | Yes |
users (Coming Soon) |
An array of user objects | Yes |
page |
A specific page object | Yes |
comment |
A specific comment | Yes |
pages
Request Parameter | Description | Type | Default | Values |
---|---|---|---|---|
sort |
Sorting method | string | latest | latest most_commented recently_commented |
page_identifiers |
Get pages by page identifiers. | string | null |
JSON-encoded array of page identifiers |
pages
endpoint returns an array of page objects of the website.- If
page_identifiers
is set, it will only return the data of those specified pages.
comments
Request Parameter | Description | Type | Default | Values |
---|---|---|---|---|
sort |
Sorting method | string | latest | latest most_upvoted |
type |
Get parent comments and replies | string | comments | comments comments_replies replies |
page_identifier |
Get comments of a specific page identified by its page identifier. | string | null |
Page identifier |
comments
endpoint returns an array of comment objects of the website.- If
page_identifier
is defined, it will only return the comments of that page. - The response will not include deleted or pending comments.
page
Request Parameter | Description | Type |
---|---|---|
page_identifier |
Page identifier of the page | string |
id |
Alternatively, you can use id provided by Hyvor Talk to fetch a page | int |
- Returns a page object if the page is found. Otherwise, it will return an error.
comment
Request Parameter | Description | Type |
---|---|---|
id |
Comment ID | int |
Objects
Page Object
{
"id": 203912,
"page_identifier": "USER-DEFINED PAGE IDENTIFIER",
"url": "https://example.com/page",
"title": "Page Title",
"created_at": 1601545752, // unix timestamp
"is_closed": false, // whether the page is closed
"comments_count": 20, // number of comments in the page
"reactions": [0,0,0,0,0,0], // 6 integers
"ratings": {
"average": 4.5, // average rating
"count": 2 // number of ratings
}
}
Comment Object
{
"id": 12309,
"markdown": "comment body in markdown",
"parent_ids": "12308, 12307", // null for parent comments
"depth": 2,
"created_at": 1601545712, // unix timestamp
"upvotes": 10,
"downvotes": 2,
"page": {
// a page object
},
"user": {
// a user object
}
}
User Object
{
"id": "2031",
"type": "hyvor",
"name": "User's Full name",
"email": "[email protected]",
"picture": "https://example.com/user.png"
}
id
is null for guest commenters.type
can behyvor
,sso
, orguest
.email
is null for Hyvor users (at this moment, we do not allow website admins access commenters emails).