Using the HelpCenter.io API


 
Ivan Penchev
Last Updated: 4 months ago

The HelpCenter.io provides you with various endpoints to read and/or manpulate the data in your help center. Let's see how you can get started with it.

API Endpoint

The endpoint of the current version of the HelpCenter.io API is:

https://api.helpcenter.io/v1/

 

Authorization

In order to use the HelpCenter.io API you are going to need an API key. While the API is in private beta you can obtain one by contacting us. Simply reach out to us and we are going to set up an API key for your help center.

Once you have your API key, you need to pass it in an apikey header with every request that you make.

 

Listing all articles

You can list all articles in a help center with a GET call the /articles resource.

GET https://api.helpcenter.io/v1/articles HTTP/1.1

Accept: application/json
apikey: <your-api-key-goes-here>

This will return all articles paginated with 100 records per page by default. You can easily change the number of articles returned in a single page using the `limit` parameter.

Use the search query parameter to search for articles by specific phrase from the title or content of your articles.

API Call: GET /articles

Parameters:

  • page - The page of articles you would like to retrieve (default: 1).
  • limit - The number of articles you want to get with a single call (default: 100).
  • category - The category you would like to get articles for with 0 being "Uncategorized" (default: all).
  • search - A query to sarch articles by.

Listing all categories

To list all categories you can make a GET call to the /categories resource.

GET https://api.helpcenter.io/categories HTTP/1.1

Accept: application/json
apikey: <your-api-key-goes-here>

This will get you back a response of all categories in the help center by default paginated by 100 items in a page like with the articles.

API call: GET /categories

Parameters:

  • page - The page of categories to retrieve.
  • limit - The number of items to get with one API call

Update an article

You could update an article via a PATCH call to the /articles/{article_id} resource with the request body containing a JSON object of the article fields that you would like to change.

This allows you to update only the fields that you want changed and leave everything else about a certain piece of content unchanged.

Here's an example HTTP call to update the title of an article:

PATCH https://api.helpcenter.io/v1/articles/{article_id} HTTP/1.1

Content-Type: application/json;charset=utf-8
apikey: <your-api-key-goes-here>

{
    "title": {
        "en": "Title of the article in Eglish",
        "bg": "Заглавие на статията"
    }
}

This will update the title in both English and Bulgarian. You could set only the languages that you want changed and leave all other untouched.

Note that the language keys that you supply for the translatable fields (thus being title, slug and content) need to be set up as primary or additional languages in the help center settings first.

API call: PATCH /articles/{article_id}

Article Object:

{
    "title": {
        "en": "The title of the article in a certain language"
    },
    "slug": {
        "en": "article-slug-in-english"
    },
    "content": {
        "en": "<p>And article content in English.</p>"
    },
    "category_id": 10,
    "type": "article|faq",
    "published": true|false
    "visibility": "public|private|link_only"
}

When making a PATCH call you could provide a single or multiple keys from the article object depending on what you would like to get updated.

When you change the title for a language that doesn't yet have a slug and you do not provide one with the same call, slug from the provided title will be automatically generate.

If you change the article visibility to link_only a share token will be automatically generated and you can obtain it from the article object included with the successful response.

Update a category

You can update a category with a PATCH call to the /categories/{category_id} resource with the request body holding a JSON object of the category fields that you would like to change.

A PATCH call to update a category will only change the data that you provide in the request body and leave everything else untouched.

An example HTTP call to update category would be:

PATCH https://api.helpcenter.io/v1/articles/{article_id} HTTP/1.1

Content-Type: application/json;charset=utf-8
apikey: <your-api-key-goes-here>

{
    "name": {
        "en": "Getting Started"
    },
    "description": {
        "en": "Step by step tutorials on how to get started with something."
    }
}

 

API Call: PATCH /categories/{category_id}

Category Object:

{
    "name": {
        "lang-key": "Category name in that language"
    },
    "description": {
        "lang-key": "Category description in that language."
    },
    "icon": "https://mywebsite.com/static/catgeory-icon.png",
    "parent_id": 10
}

 

More endpoints are coming soon so stay tuned.



Was this article helpful?