Share:
ClickHelp Documentation

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

GET Request 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 ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/search?q=full-text%20search

Code
curl -X GET ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/search?q=text&count=5&isReturnSnippets=1&projectUrls=clickhelp-documentation,api-manual

Response example

JSON
[
{
"createdOn": "2020-03-16T16:13:58",
"ftsSnippetHtml": null,
"ftsTitleHtml": null,
"fullUrl": "https://kb.clickhelp.co/articles/clickhelp-documentation/getting-topics",
"html": null,
"modifiedOn": "2020-03-16T16:14:40",
"projectTitle": "ClickHelp Documentation",
"projectUrl": "clickhelp-documentation",
"smartLink": "https://kb.clickhelp.co/smart/clickhelp-product-documentation/getting-topics",
"title": "Getting Topics",
"url": "getting-topics"
},
{
"createdOn": "2020-03-16T16:13:58",
"ftsSnippetHtml": null,
"ftsTitleHtml": null,
"fullUrl": "https://kb.clickhelp.co/articles/clickhelp-documentation/full-text-search-supported-search-operators",
"html": null,
"modifiedOn": "2020-03-16T16:14:53",
"projectTitle": "ClickHelp Documentation",
"projectUrl": "clickhelp-documentation",
"smartLink": "https://kb.clickhelp.co/smart/clickhelp-product-documentation/full-text-search-supported-search-operators",
"title": "Full-Text Search: Supported Search Operators",
"url": "full-text-search-supported-search-operators"
}
]

Response fields

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.
modifiedOnStringThe date/time when the topic was last modified, in the ISO 8601 format and the GMT timezone.
createdOnStringThe topic creation date/time in the ISO 8601 format and the GMT timezone.
indexKeywordsString[]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".
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. 


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

GET Request 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 ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/projects/clickhelp-documentation/articles?q=full-text%20search

Code
curl -X GET ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/projects/clickhelp-documentation/articles?q=full-text%20search&count=5&isReturnSnippets=1

Response example

JSON
[
{
"createdOn": "2020-03-16T16:13:58",
"ftsSnippetHtml": null,
"ftsTitleHtml": null,
"fullUrl": "https://kb.clickhelp.co/articles/clickhelp-documentation/getting-topics",
"html": null,
"modifiedOn": "2020-03-16T16:14:40",
"projectTitle": "ClickHelp Documentation",
"projectUrl": "clickhelp-documentation",
"smartLink": "https://kb.clickhelp.co/smart/clickhelp-product-documentation/getting-topics",
"title": "Getting Topics",
"url": "getting-topics"
},
{
"createdOn": "2020-03-16T16:13:58",
"ftsSnippetHtml": null,
"ftsTitleHtml": null,
"fullUrl": "https://kb.clickhelp.co/articles/clickhelp-documentation/full-text-search-supported-search-operators",
"html": null,
"modifiedOn": "2020-03-16T16:14:53",
"projectTitle": "ClickHelp Documentation",
"projectUrl": "clickhelp-documentation",
"smartLink": "https://kb.clickhelp.co/smart/clickhelp-product-documentation/full-text-search-supported-search-operators",
"title": "Full-Text Search: Supported Search Operators",
"url": "full-text-search-supported-search-operators"
}
]

Response fields

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.
modifiedOnStringThe date/time when the topic was last modified, in the ISO 8601 format and the GMT timezone.
createdOnStringThe topic creation date/time in the ISO 8601 format and the GMT timezone.
indexKeywordsString[]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".
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. 


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.