By default both the public and private API's are disabled. You must enable them to use them in Admin->Settings->Web Services API
The API is accessed from the URL: http://www.domain.com/api/index.php.
Specific methods are accessed by using the "method" query string parameter. Example:
The HelpSpot API contains both public and private methods. Private methods require authentication, public do not. Private methods are those that start with "private". For example: private.filter.get
3 return types are currently supported:
You can specify the return type you wish to receive back from the API by adding the "output" query string parameter to your API URL. If you want to receive XML then you do not need to specify the output as that is the default. Example:
The "output" parameter will accept xml, json, or php as valid values.
Private API requests require a staff members email address (or username if using Black Box) and password. There are 2 ways to pass this information to the API.
1. HTTP Basic Authentication
You may pass in the username and password via HTTP basic authentication. Libraries such as cURL generally support this.
2. URL Parameters
The information may be passed directly in the URL as parameters. Example:
The API currently expects iso-8859-1 data. Additional character sets may be supported in the future.
You may always retrieve the current and minimum versions of the API by calling the "version" method. Example:
/api/index.php?method=private.version (note this requires authentication as all private methods do)
This method will return:
If an error occurs instead of the methods XML an error XML data will be returned instead. The data is in this format:
<?xml version="1.0" encoding="iso-8859-1"?> <errors> <error> <id>2</id> <description>User authentication failed</description> </error> </errors>
More than one error tag may occur in the root errors tag.
If the API type being accessed (public or private) is not enabled in Admin->Settings an error in the following format will be returned.
<?xml version="1.0" encoding="iso-8859-1"?> <reply>Private API not enabled</reply>
Errors always return a "400 Bad Request" HTTP header as well.
The easiest way to start is by using curl or even FireFox to try some of the public API calls. Make sure the public API is enabled, then try these URL's: