KB Search

Overview

This API allows a user to perform search operations on articles and topics in scope of the portal.

Note

'articles-in-topic-tree' should not be used along with 'include-articles-in-topics' and 'exclude-articles-in-topics'. Use of 'articles-in-topic-tree' is mutually exclusive to 'include-articles-in-topics' and 'exclude-articles-in-topics'.

SecurityoAuthUser or oAuthCustomer or oAuthAnonymousCustomer

Request

path Parameters

portalID

required

number

Example: 202200000001001

query Parameters

q required	string The search query string. The string must be escaped as required by the URL syntax rules. Example: q=credit
$lang required	string The knowledge base language used for retrieving response. Must be a language accessible to user. Enum: "en-US" "en-GB" "fr-FR" "es-ES" "it-IT" "de-DE" "nl-NL" "pt-BR" "pt-PT" "da-DK" "sv-SE" "ru-RU" "fr-CA" "zh-CN" "ja-JP" "ko-KR" Example: $lang=en-US
resourceType	string Type of resource to be fetched. Enum: "article" "topic"
customFields	string A list of custom attributes to be included in the searchable fields. It should be selected as searchable attributes from the portal settings. Example: customFields=usability,validated
filter[articles-in-topic-tree]	number This parameter will restrict the search scope to the provided topic and it's sub topic. Example: filter[articles-in-topic-tree]=202200000001037
filter[include-articles-in-topics]	string The IDs of the comma seperated topic ids list will restrict the search scope to these topic Ids and their articles Example: filter[include-articles-in-topics]=202200000001061, 202200000001056
filter[exclude-articles-in-topics]	string The IDs of the comma seperated topic ids list will exclude these topics and their articles from search scope. Example: filter[exclude-articles-in-topics]=202200000001056
custom	string Custom attribute value for custom attribute of a article to be used on which filtering is required. Only non-encrypted custom attributes are supported. The custom attribute criteria is specified using a json representation. Each JSON object must have following keys: object: Value of this key represents object to which this custom attribute belongs. Supported 'object' value is 'article'. name: Value of this key represents name of the custom attribute. value: Value of this key represents value of the custom attribute to be used in search. This filtering on the custom attribute value is case-sensitive. Example: custom=[{"object":"article","name":"work_status","value":"Pending"}]
excludeRelatedTerms	string Prevents multi-search from expanding search terms into related terms, if that feature is enabled on the portal. Example: excludeRelatedTerms=yes
filter[tags]	string A comma separated list of Tag / Tag Group IDs. Tag IDs and Tag Group IDs can be mixed together. Example: filter[tags]=202200000001177,202200000001185
$pagenum	string Pagination parameter that specifies the page number of results to be returned. Used in conjunction with $pagesize. Default value: 1
$pagesize	string Pagination parameter that specifies the number of results per page. Used in conjunction with $pagenum. Default value: 10
$rangestart	string Range parameter that specifies the starting index of the range of results to be returned. Used in conjunction with $rangesize. Default value: 1
$rangesize	string Range parameter that specifies the number (range) of results to be returned. Used in conjunction with $rangestart. Default value: 10
$attribute	string The fields of the article to be returned. Example: $attribute=articleMacro, availabilityDate, averageRating, content, contentText, description, imageUrl, availableEditions, articleTypeAttributes, topic.custom.<name>, all

header Parameters

Accept-Language required	string Default: en-US Language locale accepted by client (used for locale specific fields in resource representation and in error responses). Enum: "en-US" "es-ES" "fr-FR" "it-IT" "de-DE" "nl-NL" "pt-BR" "pt-PT" "da-DK" "ru-RU" "fr-CA" "zh-CN" "ja-JP" "ko-KR" "sv-SE"
X-egain-tenant-id	string Unique identifier for tenant.
X-egain-activity-id	integer Numeric unique identifier of interaction from eGain.
X-interaction-id	string Unique identifier for interaction from other CRM applications.

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

406

Not acceptable

500

Internal server error

get/portals/{portalID}/search/kb

Request samples

curl
JavaScript
Node.js

Response samples

application/json

{"article": [{"name": "article with custom attribute",
"createdBy": 1004,
"createdByUserName": "agent_user",
"createdDate": "2023-07-17T05:29:34.000Z",
"departmentId": 999,
"hasAttachments": false,
"languageId": 1,
"lastModifiedBy": 1004,
"lastModifiedByUserName": "agent_user",
"lastModifiedDate": "2023-07-17T05:30:17.000Z",
"textMetadata": {"highlightMetadata": [{"attributeName": "name",
"characterRange": [{"firstPos": 0,
"lastPos": 7
}
]
}
]
},
"topicBreadcrumb": [{"topicSummary": [{"name": "Folder WF1",
"link": {"rel": "self",
"href": "/knowledge/portalmgr/v3/portals/409600000001273/topics/777700000032607"
},
"id": 777700000032607
}
]
}
],
"versionId": 777700000178603,
"id": 777700000096828
}
],
"topic": [{"name": "Topic with custom attribute articles",
"articleCountInTopic": 2,
"articleCountInTopicTree": 2,
"createdBy": 1,
"createdDate": "2022-11-17T08:44:38.000Z",
"departmentId": 999,
"lastModifiedBy": 1,
"lastModifiedDate": "2022-11-17T08:44:38.000Z",
"textMetadata": {"highlightMetadata": [{"attributeName": "name",
"characterRange": [{"firstPos": 0,
"lastPos": 4
}
]
}
]
},
"id": 777700000001022,
"childCount": 0
}
],
"query": "article",
"isSpellingCorrected": false,
"searchIncludesRelatedTerms": false,
"tagCategories": [{"name": "colors",
"id": 409600000144024,
"tagGroup": [{"name": "primary_colors",
"id": 409600000144059
},
{"name": "secondary_colors",
"id": 409600000144063
}
],
"tag": [{"name": "red",
"id": 409600000144027
},
{"name": "violet",
"id": 409600000144030
}
]
},
{"name": "colors2",
"id": 409600000144124,
"tagGroup": [{"name": "cool_colors",
"id": 409600000144163
},
{"name": "warm_colors",
"id": 409600000144159
}
],
"tag": [{"name": "yellow",
"id": 409600000144129
},
{"name": "orange",
"id": 409600000144131
},
{"name": "green",
"id": 409600000144130
},
{"name": "purple",
"id": 409600000144132
}
]
}
],
"paginationInfo": {"count": 2,
"pagenum": 1,
"pagesize": 25
}
}