Home → API Manual → Web Service API → API Basics: URL, Methods, Return Formats, Authentication

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

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:

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

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'

Basic Authentication

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.

Example:

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

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:

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:

Knowledge Tags
API  /  API Errors  / 

This page was: Helpful | Not Helpful
← Web Service API Overview API Error Codes →