API Basics: URL, Methods, Return Formats, Authentication

How to Enable the API

By default both the public and private API's are disabled. You must enable them to use them in Admin->Settings->Web Services API

API URL

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:

http://www.domain.com/api/index.php?method=request.get

Public vs Private

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

Return Format

3 return types are currently supported:

  • XML (this is the default)
  • JSON
  • Serialized PHP

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:

/api/index.php?method=request.get&output=json

The "output" parameter will accept xml, json, or php as valid values.

Private API Authentication

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:

/api/index.php?method=request.get&username=tim@domain.com&password=abc123

Character Set

The API currently expects iso-8859-1 data. Additional character sets may be supported in the future.

Version Information

You may always retrieve the current and minimum versions of the API by calling the "version" method. Example:

/api/index.php?method=version

/api/index.php?method=private.version (note this requires authentication as all private methods do)

This method will return:

  • version - The current version of the API the installation is using.
  • min_version - The minimum version of the API a client application must support in order to operate correctly with the server installation. For instance, if the server API is currently 3.0 with a minimum version of 2.0 then a client written to use the 1.0 API would not function properly. Clients should check this value before using the API.

Errors

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 Try the API

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:

  • Get the version:
    /api/index.php?method=version
  • List the public knowledge books:
    /api/index.php?method=kb.list
  • Get an existing request in the system:
    /api/index.php?method=request.get&accesskey=####(use the access key for the request)

Knowledge Tags


This page was: Helpful | Not Helpful