Share:
ClickHelp Documentation

Getting Topics

You can use ClickHelp API to obtain information on projects in your portal and topics in those projects. You can also obtain HTML content, title and other properties of a specific topic via the API.

Information If you want to embed content from ClickHelp into your application, there is a simpler way to do that. We recommend that you consider using Context Help first and use the API only if the Context Help functionality is not enough.

Functions List

Get All Topics in a Project

You can obtain the full list of topics in a specified project or publication.

GET /api/v1/projects/{projectUrl}/articles HTTP/1.1

Response Fields

FieldTypeDescription
IDString

Topic ID is an alphanumeric topic identifier that becomes a part of the full topic URL in the browser address bar. The topic ID is unique inside one project or publication (e.g. "full-text-search")

fullUrlString

Full topic URL which can be used to open the topic in a web browser.

For example: "https://my-portal.clickhelp.co/articles/some-documentation/full-text-search/"

titleStringThe topic title. 
projectTitleString The title of the project or publication to which the topic belongs. 
projectUrlString The URL identifier of the project or publication to which the topic belongs (e.g. "clickhelp-documentation").
htmlString The HTML content of the topic. This field is populated only when getting a specific single topic via API and is not populated for responses which return multiple topics.
ftsTitleHtmlString The HTML markup of the topic title with a full-text search query matches highlighted. For example, if you search for the "text" keyword, the highlighted topic title can be "Full-Text Search". This field is populated only for full-text search queries executed with the isReturnSnippets parameter greater than zero.
ftsSnippetHtmlString The HTML markup of a topic content snippet with a full-text search query matches highlighted. Similar to text snippets you see for search results in Google. This field is populated only for full-text search queries executed with the isReturnSnippets parameter greater than zero. 

Request Example

Below, is an example of a CURL command line you can use in a batch file to get all topics from the "imported-manual" project.

curl -X GET ^
  --basic ^
  --user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
  --cacert comodo.ca-bundle ^
  https://doc.clickhelp.co/api/v1/projects/imported-manual/articles

Response Example

{[  
  {  
    "fullUrl":"http://doc.clickhelp.co/articles/imported-manual/full-text-search",
    "html":null,
    "projectName":"ClickHelp Documentation",
    "projectUrl":"clickhelp-documentation",
    "title":"Full-Text Search",
    "url":"full-text-search"
  },
  {  
    "fullUrl":"http://doc.clickhelp.co/articles/imported-manual/getting-topics",
    "html":null,
    "projectName":"ClickHelp Documentation",
    "projectUrl":"clickhelp-documentation",
    "title":"Getting Topics",
    "url":"getting-topics"
  }
]}

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

  • 200 (OK)
    The status request has succeeded, the response body contains the task progress information.
  • 403
    The user does not have the permission to access the project or publication.

Get Specific Topic

You can obtain information on a specific topic using the sample request below. This operation can be performed by both authenticated and anonymous users (in this case, only topics from public publications are available). Topic availability is determined by the user's permissions in ClickHelp.

GET /api/v1/projects/{projectUrl}/articles/{topicUrl} HTTP/1.1

Response Fields

FieldTypeDescription
IDString

Topic ID is an alphanumeric topic identifier that becomes a part of the full topic URL in the browser address bar. The topic ID is unique inside one project or publication (e.g. "full-text-search")

fullUrlString

Full topic URL which can be used to open the topic in a web browser.

For example: "https://my-portal.clickhelp.co/articles/some-documentation/full-text-search/"

titleStringThe topic title. 
projectTitleString The title of the project or publication to which the topic belongs. 
projectUrlString The URL identifier of the project or publication to which the topic belongs (e.g. "clickhelp-documentation").
htmlString The HTML content of the topic. This field is populated only when getting a specific single topic via API and is not populated for responses which return multiple topics.
ftsTitleHtmlString The HTML markup of the topic title with a full-text search query matches highlighted. For example, if you search for the "text" keyword, the highlighted topic title can be "Full-Text Search". This field is populated only for full-text search queries executed with the isReturnSnippets parameter greater than zero.
ftsSnippetHtmlString The HTML markup of a topic content snippet with a full-text search query matches highlighted. Similar to text snippets you see for search results in Google. This field is populated only for full-text search queries executed with the isReturnSnippets parameter greater than zero. 

Request Example

Below, is an example of a CURL command line you can use in a batch file to get a topic.

curl -X GET ^
  --basic ^
  --user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
  --cacert comodo.ca-bundle ^
  https://doc.clickhelp.co/api/v1/projects/imported-manual-publication/articles/full-text-search

Response Example

{  
  "fullUrl":"http://doc.clickhelp.co/articles/imported-manual/full-text-search",
  "html":"<!DOCTYPE html>\r\n<html>...",
  "projectName":"ClickHelp Documentation",
  "projectUrl":"clickhelp-documentation",
  "title":"Full-Text Search",
  "url":"full-text-search"
}

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

  • 200 (OK)
    The status request has succeeded, the response body contains the task progress information.
  • 403
    The user does not have the permission to access the project or publication.
  • 404
    There is no project or publication with the given project URL. Or, the project / publication exists, but there is no topic with the given topic URL.