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.

  1. Server-side: Using an API key
  2. 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).