API: Full-Text Search
You can run full-text search queries via ClickHelp API. Unlike the data-changing functions of the API, full-text search operations do not require authentication and can be performed anonymously. They can also be performed from JavaScript using CORS, which allows cross-domain requests.
Full-text search requests list:
Search the Entire Portal
![]() |
Search the entire portal |
/api/v1/search?q={searchQuery}&count={maxResCount}&isReturnSnippets={isReturnSnippets}&projectUrls={projectUrls}&lang={lang} HTTP/1.1 |
Runs full-text search in all projects available to the current user. If the user is unauthenticated, only public publications are searched. If the user is authenticated, a search is performed in projects and publications the user has access to. You can also apply an additional filter to search only the projects and publications listed in the projectUrls parameter.
Authorization
This request is using basic authentication, but can also be called anonymously, without any authentication.
Request parameters
Query string parameters
searchQuery required |
String | The full-text search query. It may contain double quotes for phrase search and other supported full-text search operators. |
count optional |
Integer | Defines the maximum count of top search results to be returned. If this parameter is omitted, the top 10 results are returned. If the value is a negative number, all search results are returned regardless of their total count. |
isReturnSnippets
OPTIONAL
|
Integer | If set to 1 (or any value greater than zero), search results will contain highlighted HTML for topic titles and highlighted content snippets similar to those in Google. That is, whether the ftsTitleHtml and ftsSnippetHtml fields will be populated in search results. |
projectUrls optional |
String | A comma-separated list of project URL identifiers. If specified, only the given projects/publications will be searched. If some are not available to the currently authenticated user, they will be excluded from the search list. If both projectUrls and lang are specified, the system will combine both conditions (projects with specified URLs and having the specified language will be searched). |
lang optional |
String |
A language code in the format languagecode2-country/regioncode2, where languagecode2 is a lowercase two-letter code derived from ISO 639-1, and country/regioncode2 is derived from ISO 3166. Usually, it consists of two uppercase letters or a BCP-47 language tag (e.g., en-US or zh-Hans). If specified, only projects of the given language are searched. If both projectUrls and lang are specified, the system will combine both conditions (projects with specified URLs and having the specified language will be searched).
|
Request example
Below are examples of CURL command lines you can use in a batch file to get search results for the entire portal.
Code |
curl -X GET ^ |
Code |
curl -X GET ^ |
Response example
JSON |
[ |
Response fields
ID | String | 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") |
fullUrl | String |
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/" |
title | String | The topic title. |
projectTitle | String | The title of the project or publication to which the topic belongs. |
projectUrl | String | The URL identifier of the project or publication to which the topic belongs (e.g. "clickhelp-documentation"). |
html | String | 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. |
modifiedOn | String | The date/time when the topic was last modified, in the ISO 8601 format and the GMT timezone. |
createdOn | String | The topic creation date/time in the ISO 8601 format and the GMT timezone. |
indexKeywords | String[] | An array of index keywords associated with the topic, as displayed in the index keywords editor. Hierarchical keywords are represented as comma-separated values. For example, if the parent keyword is "parent" and its child is "child", the corresponding array item is "parent,child". |
ftsTitleHtml | String | 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. |
ftsSnippetHtml | String | 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. |
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
Returned if the information was retrieved successfully. The response body contains the data.
Search in a Specific Project
![]() |
Search in a specific project |
GET /api/v1/projects/{project/publication-id}/articles?q={searchQuery}&count={maxResCount}&isReturnSnippets={isReturnSnippets} HTTP/1.1 |
Runs full-text search in a specific project. If the user is unauthenticated, only public publications can be searched. If the user is authenticated, the search can be performed in any project or publication the user has access to.
Authorization
This request is using basic authentication, but can also be called anonymously, without any authentication.
Request parameter
Path parameters
project/publication-id required |
string | The ID of the project or the publication to search within. |
Query string parameters
searchQuery required |
String | The full-text search query. It may contain double quotes for phrase search and other supported full-text search operators. |
maxResCount optional |
Integer | Defines the maximum count of top search results to be returned. If this parameter is omitted, the top 10 results are returned. If the value is a negative number, all search results are returned regardless of their total count. |
isReturnSnippets optional |
Integer | If set to 1 (or any value greater than zero), search results will contain highlighted HTML for topic titles and highlighted content snippets similar to those in Google. That is, whether the ftsTitleHtml and ftsSnippetHtml fields will be populated in search results. |
Request example
Below are examples of CURL command lines you can use in a batch file to get search results for the entire portal.
Code |
curl -X GET ^ |
Code |
curl -X GET ^ |
Response example
JSON |
[ |
Response fields
ID | String | 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") |
fullUrl | String |
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/" |
title | String | The topic title. |
projectTitle | String | The title of the project or publication to which the topic belongs. |
projectUrl | String | The URL identifier of the project or publication to which the topic belongs (e.g. "clickhelp-documentation"). |
html | String | 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. |
modifiedOn | String | The date/time when the topic was last modified, in the ISO 8601 format and the GMT timezone. |
createdOn | String | The topic creation date/time in the ISO 8601 format and the GMT timezone. |
indexKeywords | String[] | An array of index keywords associated with the topic, as displayed in the index keywords editor. Hierarchical keywords are represented as comma-separated values. For example, if the parent keyword is "parent" and its child is "child", the corresponding array item is "parent,child". |
ftsTitleHtml | String | 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. |
ftsSnippetHtml | String | 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. |
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
Returned if the information was retrieved successfully. The response body contains the data.
403: Forbidden
The user does not have permission to access the project or publication.
404: Not Found
There is no project or publication with the given URL.