ClickHelp User Manual

ClickHelp API

Every ClickHelp portal is equipped with REST API to enable task automation and to help you integrate your documentation workflow into the existing business processes.


REST API Base URL

All URLs in the reference documentation use the following base URL:

https://{your-portal-URL}/api/v1/

By default, your-portal-URL looks like hedronlabs.clickhelp.co, where hedronlabs is the name of your portal. If you're using a custom domain, e.g., docs.hedronlabs.orgit is used instead. 

All requests to the ClickHelp REST API are served over HTTPS. Unencrypted HTTP is not supported. Besides, ClickHelp uses TLS 1.2; any version below that is not supported.

Authentication

Most requests to ClickHelp REST API use Basic authentication, although some can be made anonymously. In short, you will use your ClickHelp account login as the username and your API key as the password for HTTP Basic authentication. So make sure to pass the -u (--user) flag:

Bash (Unix Shell)
    --basic ^
--user "login:api-key"

When authenticating, you need to supply your login and the API key, not your password.

You can find your login and generate an API key in your profile. For instructions, see the Get API Key topic. Note that only Contributors can generate API keys.

Response Status Codes

All API requests will respond with a certain code — it may be a success or an error code. Below is the list of all status codes ClickHelp API may return.

Success Codes

200 OK The request succeeded. The result meaning of "success" depends on the HTTP method.
201 Created
The request succeeded, and a new resource was created as a result.
204 No Content
The request succeeded. 

Error Codes

API should return a meaningful message along with the error response code that will hint at what went wrong. Additionally, you can consult API Troubleshooting for the steps for resolving errors. If that doesn't help or the system returns an unclear error message, feel free to contact support@clickhelp.com, providing details. 

400 Bad Request
The data in your request is invalid, and the server cannot or will not process it — e.g., malformed request syntax, invalid request message framing, etc.
401 Unauthorized
The login or API Key is invalid, no login information is provided, your user account is disabled, or the Authorization HTTP header of your request is corrupted — see the response body for details. Make sure you're not providing your password instead of the API key.
403 Forbidden
You have no permission to work with the API or to perform the requested action. See the response body for details.
404 Not Found
The resource you are looking for cannot be found. This may happen if the URL you specified is invalid or the resource you refer to does not exist.
409 Conflict
The action you tried to perform resulted in a data conflict, which usually means duplicated identifiers (for example, creating a user with a name that already exists). See the response body for details.
500 Internal Server Error
Something went wrong when processing your request; see the response body for details.
501 Not Implemented
You have attempted to do something not currently supported by the API. If you get this response code, please contact us and let us know what you are trying to achieve.

Error Response Body

For errors, the HTTP response body always contains a JSON object having the following fields:

Field Description
Message Exception message with details.
ExceptionType The type of exception.
ExceptionDetail Reserved for future use. 
StackTrace Reserved for future use.

Note on Responses

There are a couple of things that are common for all responses.

  • All POST methods eturn the location of the related resource (topic, TOC node, etc.) in the Location header.
  • All PATCH methods return the full updated resource, as if you ran the GET request afterwards.

Note on API Reference

Below are some things you should know before consulting ClickHelp API reference.

  • All examples from the reference include only their specific flags/parameters for cURL and do not include the common flags specifying the CA bundle file and the authentication data. Make sure you include them in all requests:
    Bash (Unix Shell)
        --user "login:api-key" ^
    --cacert comodo.ca-bundle ^
  • The reference contains API request examples using the cURL utility. An important thing to note about the examples is that they use the --cacert command line parameter. It specifies the name of the CA Bundle file — a file with the root and intermediate certificates of the certification authority that issued the SSL certificate of the target endpoint. cURL uses this file to verify the endpoint SSL certificate. This type of file is normally available on the certification authority website, and you can download it.
    If you are using the default domain name {portal-name}.clickhelp.co, you can use this CA Bundle file. If you are using a custom domain name with your own SSL certificate, please request the CA Bundle file from your certification authority.
  • Parameters are considered required by default. All parameters that are not required are marked as either [optional] or [deprecated].