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
- Authentication
- Response Status Codes
- Success Codes
- Error Codes
- Note on Responses
- Note on API Reference
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.org, it 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 ^ |
| 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].
Read further about ClickHelp REST API: