Skip to content
/
Filtering
Last updated

Filtering Capabilities

The Answers API provides flexible filtering options to ensure that queries return only the most relevant content. Filters can be applied at request time to narrow down the search space based on metadata such as article type, topics, tags, and user profiles.

Supported Filters

1. Article Type (Certified Answers)

  • Ensures that only articles of the articleType FAQ are considered during the Certified Answers pipeline.
  • Learn more by reading the Certified Answers guide.

2. Topic IDs ($filter[topicIds])

  • Restricts the scope of the content retrieved by the Answers API to only the provided topics.
  • Accepts an array of IDs (1–20) for multi-topic filtering.
  • Example:
    curl -X POST \
  'https://<API_DOMAIN>/core/aiservices/v4/<YOUR_PORTAL_ID>/answers?q=<YOUR_QUERY>>&$filter[topicIds]=<YOUR_TOPIC_ID>&$lang=<YOUR_LANGUAGE_CODE>' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

3. Tags ($filter[tags])

  • Restricts the scope of content retrieved by the Answers API using hierarchical category tags.
  • Each key is a Category Tag ID, and each value is an array of Tag IDs for that category.
  • Supports up to 15 categories, each with up to 200 tags.
  • Example:
curl -X POST \
  'https://<API_DOMAIN>/core/aiservices/v4/<YOUR_PORTAL_ID>/answers?q=<YOUR_QUERY>&$lang=<YOUR_LANGUAGE_CODE>&$filter[tags]={<YOUR_CATEGORY_TAG_ID>:[<YOUR_TAG_IDS>]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
  • $filter[tags] → Object of category tags and tag IDs
    • Example: {"PROD-1234": ["PROD-2000", "PROD-2001"] }

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

  • Restricts the scope of content retrieved by the Answers API based on a specific user profile ID.
  • Useful for tailoring answers to a given persona (e.g., customer vs. agent).
  • Example:
curl -X POST \
  "https://<API_DOMAIN>/core/aiservices/v4/<YOUR_PORTAL_ID>/answers?q=<YOUR_QUERY>&$lang=<YOUR_LANGUAGE_CODE>&$filter[userProfileID]=<YOUR_USER_PROFILE_ID>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Combining Filters

Filters can be combined to achieve fine-grained control. For example, restricting by topicIds, tags, and userProfileID in the same request:

curl -X POST \
  'https://<API_DOMAIN>/core/aiservices/v4/<YOUR_PORTAL_ID>/answers?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.
Previous page
Next page