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

	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.

Copy Code

Code

curl -X GET ^
--cacert comodo.ca-bundle ^
https://mycompany.clickhelp.co/api/v1/search?q=full-text%20search

Copy Code

Code

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

Response example

Copy Code

JSON

[
    {
        "createdOn": "2020-03-16T16:13:58",
        "ftsSnippetHtml": null,
        "ftsTitleHtml": null,
        "fullUrl": "https://mycompany.clickhelp.co/articles/clickhelp-documentation/getting-topics",
        "html": null,
        "modifiedOn": "2020-03-16T16:14:40",
        "projectTitle": "ClickHelp Documentation",
        "projectUrl": "clickhelp-documentation",
        "smartLink": "https://mycompany.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://mycompany.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://mycompany.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

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.

Copy Code

Code

curl -X GET ^
--cacert comodo.ca-bundle ^
https://mycompany.clickhelp.co/api/v1/projects/clickhelp-documentation/articles?q=full-text%20search

Copy Code

Code

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

Response example

Copy Code

JSON

[
    {
        "createdOn": "2020-03-16T16:13:58",
        "ftsSnippetHtml": null,
        "ftsTitleHtml": null,
        "fullUrl": "https://mycompany.clickhelp.co/articles/clickhelp-documentation/getting-topics",
        "html": null,
        "modifiedOn": "2020-03-16T16:14:40",
        "projectTitle": "ClickHelp Documentation",
        "projectUrl": "clickhelp-documentation",
        "smartLink": "https://mycompany.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://mycompany.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://mycompany.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

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.

ClickHelp - Online Documentation and Help Authoring Tool

Tutorial Videos
ClickHelp Blog
ClickHelp Free Trial
Contact ClickHelp Support Team
ClickHelp Team on Medium
ClickHelp Team on Twitter
Send feedback on this topic to ClickHelp Team .