PHPKB API Reference Guide

This module enables you to use REST API through your PHPKB software. It includes a variety of useful commands in order to get information from your PHPKB installation remotely, through third-party applications. The PHPKB API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.

A REST API defines a set of functions in which developers can perform requests and receive responses via HTTP protocols such as GET and POST. This is exactly what you will get from our product. Nothing less, nothing more. If you are unsure about your coding skills or you do not understand what exactly an API is, feel free to raise a comment with your specific question.

PHPKB API Reference Guide

This document provides details on how to use the API available in PHPKB knowledge base management software. It acts as a reference guide and covers topics such as enabling the API server, generating the API verification keys and preparing the request URL parameters for submitting a valid request to the API server.

The API can be called through the browser directly, which is the easiest approach. If your knowledge base is installed at  https://www.yoursite.com/phpkb/ then the API server can be accessed from  https://www.yoursite.com/phpkb/api.php.

1. Enabling API Server

The very first step is to enable the API server from the "Manage Settings > Miscellaneous" section of the admin control panel.

1. Enable API : This setting should be checked to enable API, otherwise, the system would reject your request.
2. Verify API Key : To constructing a more secure API system, the API requires an authorization key to validate the request and return results. For more details, refer to "How to generate an API Key?" section below.
3. Secure API Connection : If you want that API system should be accessed through SSL via https:// then enable this setting. For instance, if the setting is enabled and you are accessing the API via http:// (without "s") then your request would be discarded.
4. Referrers : Enter the comma separated value of domains that can generate a request for API.
5. Save Logs : An optional setting to store the log of every request made to the API and response generated by the API.

How to generate an API Key?

You can generate an API key from "API > Keys" section of the admin panel as shown below.

It is recommended to add some alphanumeric string in the key field and press "Save" button. The system will store the string and output the "MD5 Hash" result as the key. The "MD5 Hash" value of the string must be passed to the API server (api.php) as "key" parameter along with other parameters, otherwise, the API will reject your request.

Example: If the MD5 Hash value generated for your key is d13658044c8883055db782f1956b3561 then while calling API user must add a key parameter like
https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561

2. Calling the API Server

Calls should be made to the API server available at https://www.yoursite.com/phpkb/api.php . It will return data/errors in JSON format.

How to prepare the query string for accessing the required data through API?

Here is the detailed explanation of various parameters that can be passed to the API Server via query string as variables.

1. key : If "Verify API Key" setting is enabled settings then, it is a mandatory field and should be passed with each request. Parameter name for this is key and as explained earlier, the value of this parameter should be "MD5 Hash" value of the key. Therefore, the complete parameter string would be in form of key=value

    key=d13658044c8883055db782f1956b3561

2. call : It specifies the module that needs to be invoked.

Possible values can be:

• articles
• news
• categories
• search

This is a mandatory field and should not be left blank. The query string for this parameter would be in the form of call=articles

3. method : This parameter can be used when you want to fetch a list of items.

Possible values for different modules

• articles: featured, recent, popular, rated
• news: recent

Applicable on news and articles module

Query String: method=recent

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=articles&method=recent

4. cid : To view the articles of a specific category, enter the category id in this field.

Applicable to the articles and search modules.

Query String: cid=1

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=articles&cid=1

5. limit : If you want to bound the results to a certain threshold then specify the numeric count in this field.

Applicable to all modules.

Query String: limit=2

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=articles&method=recent&limit=2

6. fields : Enter the comma separated values of article fields that you want to access. If the field is empty, then all the article fields would be returned.

Possible values of field parameter for different modules:

• articles: language, author, title, content, keywords, summary, labels, created, published, updated, link, attachments, categories
• news: language, author, title, content, created, updated, hits, link
• categories: id, language, name, description, status, link
• search:
  • articles: all values of articles module
  • news: all values of the news module
  • categories: all values of categories module

Applicable to all modules.

Query String: fields=title,link

A link is the URL of the article.

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=articles&cid=1&limit=2&fields=title,link

7. mode : Possible values are text or html. If you want to see the contents in text or HTML mode, then this is applicable.

Applicable to articles and news modules. The mode will not work when you want to view details of single item.

Query String: mode=text/html

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=articles&cid=1&limit=2&fields=title,link&mode=text

8. charCount : This field is valid only for text mode. In case, you need to see any number of characters in content, then charCount is applicable.

Applicable to articles and news modules.

Query String: charCount=100

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=articles&cid=1&limit=2&fields=title,link&mode=text&charCount=100

9. id : If you want to fetch the value of a specific item, then specify the ID of the item in this field.

Applicable to articles, news, categories modules.

• articles: This field has higher priority than "method" and "cid" that means if you have specified "cid" and method parameter along with this, only the details of the article would be returned.
• news: higher priority than method parameter
• categories: this field would fetch the immediate children of the category whose ID is passed

Query String: id=1

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=articles&id=1&fields=title,link

10. lang : This parameter is applicable only to the ML (multi-language) editions of PHPKB knowledge base software. It lets you specify the Language ID for which you want to fetch the list of articles/news/categories. By default, the script returns English articles/news/categories. Please note, this field has less precedence than "cid" and "id".

Applicable to all modules.

Query String: lang=1

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=articles&lang=2&method=recent&limit=2&fields=title,link

11. k : keyword that is to be searched

Applicable to the search module.

Query String: k=forgot password

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=search&k=forgot+password&mode=text

12. for : the area where to search the keyword

Possible values: articles/news/categories

Applicable to the search module.

Query String: for=articles

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=search&for=articles&k=forgot+password&mode=text

13. in : to specify the fields in which the system will search for keywords.

Possible values for different modules:

• articles: all/id/title/content/keywords
• news: all/id/title/content
• categories: all/id/name/description

The default value is "all"

"id" would only be searched if search mode is set to "like". Full text is applicable only on character fields.

Applicable to the search module.

Query String: in=title

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=search&for=articles&in=title&k=forgot+password&mode=text

14. filter : to specify if the system should search for any words, all words or exact match of the search keywords

Possible values: any/all/exact

The default value is "any"

Applicable to the search module.

Query String: filter=all

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=search&filter=all&k=forgot+password&mode=text

15. subcats : This parameter lets you specify if the search should also include sub-categories of the specified category ID.

Possible values: yes/no

The default value is "no"

Applicable to the search module.

Query String: subcats=yes

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=search&filter=all&k=forgot+password&mode=text&cid=1&subcats=yes

16. sort : This parameter lets you specify the sort order of search results

Applicable to the search module.

Possible values for different modules:

• articles: relevance/popularity/rating
• news: relevance/popularity
• categories: relevance/popularity

The default value is "relevance" for all modules.

Query String: sort=popularity

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=search&for=articles&k=forgot+password&mode=text&sort=popularity

17. attachments : This parameter lets you specify if the search should also be performed on the text content of attached files 

Possible values: yes/no

The default value is "no"

Applicable to the search module.

Query String: attachments=yes

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=search&k=forgot+password&mode=text&attachments=yes

18. custom-fields : This parameter lets you specify if the search should also be performed on the values of custom fields.

Possible values: yes/no

The default value is "no"

Applicable to the search module.

Query String: custom-fields=yes

    https://www.yoursite.com/phpkb/api.php?key=d13658044c8883055db782f1956b3561&call=search&k=forgot+password&mode=text&custom-fields=yes

3. Response Codes

Success or error codes returned by PHPKB API would give you explanation about the status of your request in case you'll experience any issues:

Code	Status	Description
200	OK	Successful request.
400	Bad Request	Invalid request and/or request parameters
401	Bad Authentication Data	Authentication is required in order to retrieve data. Either invalid api key or wrong format of api key
404	Not Found	When the requested resource is not found. For example API request was made on invalid URL.
500	Internal Server Error	The general catch-all error when the server-side throws an exception
503	Service Unavailable	API interface unavailable or disabled