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 be hyvor, sso, or guest.
email is null for Hyvor users (at this moment, we do not allow website admins access commenters emails).