Filtering Capabilities

The Search API provides powerful filtering options to help narrow down search results and ensure that users only see the most relevant knowledge content. Filters can be applied at request time to refine results based on topics, tags, user profiles, or language codes. This ensures a more contextual and precise search experience across customer and agent-facing applications.

Supported Filters

1. Topic IDs ($filter[topicIds])

  • Restricts the search scope to only the provided topic IDs.
  • Accepts an array of IDs (1–20) for multi-topic filtering.
  • Useful for targeting content within specific knowledge areas, product lines, or support categories.
  • Example:
    Copy
    Copied
    curl -X POST \
  'https://<API_DOMAIN>/knowledge/portalmgr/v4/<YOUR_PORTAL_ID>/search/?q=<YOUR_QUERY>&$filter[topicIds]=<YOUR_TOPIC_ID>&$lang=<YOUR_LANGUAGE_CODE>' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

2. Tags ($filter[tags])

  • Restricts search results using hierarchical category tags.
  • Each key is a Category Tag ID, and each value is an array of Tag IDs under that category.
  • Supports up to 15 categories, each with up to 200 tags.
  • Ideal for narrowing results to specific business units, regions, or products.
  • Example:
    Copy
    Copied
    curl -X POST \
  'https://<API_DOMAIN>/knowledge/portalmgr/v4/<YOUR_PORTAL_ID>/search/?q=<YOUR_QUERY>&$filter[topicIds]=<YOUR_TOPIC_ID>&$lang=<YOUR_LANGUAGE_CODE>&$filter[tags]={<YOUR_CATEGORY_TAG_ID>:[<YOUR_TAG_IDS>]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

3. User Profile ID ($filter[userProfileID])

  • Restricts results to content available for a specific user profile.
  • Ensures that customers, partners, and agents only see articles aligned with their access level.
  • Commonly used to differentiate between customer-facing and internal-only knowledge.
  • Example:
    Copy
    Copied
    curl -X POST \
  'https://<API_DOMAIN>/knowledge/portalmgr/v4/<YOUR_PORTAL_ID>/search/?q=<YOUR_QUERY>&$lang=<YOUR_LANGUAGE_CODE>&$filter[userProfileID]=<YOUR_USER_PROFILE_ID>' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

4. Language Code ($lang)

  • Restricts search results to a specific language.
  • Ensures users receive localized content, improving the multilingual self-service experience.
  • Accepts standard ISO language codes (e.g., en-US, es-ES, fr-FR).
  • Example:
    Copy
    Copied
    curl -X POST \
  'https://<API_DOMAIN>/knowledge/portalmgr/v4/<YOUR_PORTAL_ID>/search/?q=<YOUR_QUERY>&$lang=<YOUR_LANGUAGE_CODE>' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Combining Filters

Filters can be combined in a single request for fine-grained control. For example, filtering by topic IDs, user profile, tags, and language simultaneously:

Copy
Copied
curl -X POST \
  'https://<API_DOMAIN>/knowledge/portalmgr/v4/<YOUR_PORTAL_ID>/search/?q=<YOUR_QUERY>&$lang=<YOUR_LANGUAGE_CODE>&$filter[topicIds]=<YOUR_TOPIC_ID>&$filter[userProfileID]=<YOUR_USER_PROFILE_ID>&$filter[tags]={<YOUR_CATEGORY_TAG_ID>:[<YOUR_TAG_IDS>]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Placeholders to Replace

  • <API_DOMAIN>: The domain of your API.
  • <YOUR ACCESS TOKEN>: Your OAuth 2.0 access token.
  • <YOUR_QUERY>: The query you send to the API.
  • <YOUR PORTAL ID>: Your eGain portal id.
  • <YOUR LANGUAGE CODE>: The language code you'd like to use with your portal.
  • <YOUR TOPIC ID>: The eGain topic id(s) you want to filter by. It will limit the scope of results to use for answer generation to content belonging to those topic ids.
  • <YOUR USER PROFILE_ID>: The eGain user profile id you want to filter by. This will reduce the scope of eGain articles by only using content available to that specific user profile.
  • <YOUR CATEGORY TAG_ID>: The eGain category tag id you want to filter by.
  • <YOUR TAG IDS>: The eGain tag ids belonging to the category tag id provided.