4.2. 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
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:
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
3 return types are currently supported:
- XML (this is the default)
- 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:
The "output" parameter will accept xml, json, or php as valid values.
Private API Authentication
API Authentication Tokens
API Tokens allow requests to be authenticated to the Private API without using a user's credentials. API keys are generated in the staff preferences area of HelpSpot user's profile. The API key generated by a given staff member will have the same rights and roles as the user who generated the API key.
To use an API key after it is generated the API key needs to be passed in an "Authorization" header with the value of "Bearer" + the API key. Here is a CURL example:
curl "http://mydomain.com/api/index.php?method=private.request.get&xRequest=13209" \
-H 'Authorization: Bearer 1|5VdNXJEtsPoFpX1KH5yc0BO2wlCqDp0sRTxZtox3'
Private API need a staff member's email address (or username if using Black Box / LDAP auth) and password. There are 2 ways to pass this information to the API. Note that basic authentication to the API is disabled if SAML2 auth is used.
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. This is not are recommended way of authenticating as your credentials will appear in the URL and may be logged etc.
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:
- 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.
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:
- List the public knowledge books:
- Get an existing request in the system:
/api/index.php?method=request.get&accesskey=####(use the access key for the request)