# Hybrid Search

The Search API is a hybrid search service that combines semantic understanding with keyword precision to deliver fast, contextual, and relevant results from your enterprise knowledge base. It enables secure, role-aware access to articles, FAQs, and documentation across customer, agent, and employee interfaces. Each query returns a ranked list of results with snippets, metadata, and relevance scores.

Endpoint: GET /{portalID}/search
Security: oAuthUser, oAuthCustomer, oAuthAnonymousCustomer

## Query parameters:

  - `q` (string, required)
    The search query string. The string must be escaped as required by the URL syntax rules.
    Example: "What is a loan?"

  - `$filter[userProfileID]` (string)
    The ID of the user profile.
    Example: "PROD-1030"

  - `$lang` (string, required)
    The language that describes the details of a resource. Resources available in different languages may differ from each other.  If lang is not passed, then the portal's default language is used.
    Enum: "en-US", "fr-FR", "en-GB", "es-ES", "it-IT", "nl-NL", "da-DA", "sv-SE", "pt-PT", "fi-FI", "no-NB", "no-NN", "ja-JA", "de-DE", "pt-BR", "zh-CN", "zh-TW", "ko-KO", "ru-RU", "el-EL", "tr-TR", "pl-PL", "cs-CS", "sk-SK", "hu-HU", "sr-SR", "ar-SA", "hr-HR", "ro-RO", "th-TH", "de-AT", "vi-VN", "id-ID", "ms-MY", "fil-PH", "fr-CA", "hi-IN", "uk-UA", "bg-BG", "sl-SI", "xx-XX"

  - `$filter[tags]` (object)
    An object where each key is a Category Tag ID (numeric string),  
and each value is an array of Tag IDs for that category.
 Note:
  - The '$filter[tags]' query parameter JSON value should be url encoded.
  - Some developer tools for invoking APIs may not url encode the '$filter[tags]' query parameter JSON value by default. Ensure that only url encoded values are used.
  - Example of JSON value: {"BASE-40845":["BASE-40849","BASE-40853"]}
  - Example of URL encoded value: %7B%22BASE-40845%22%3A%5B%22BASE-40849%22%2C%22BASE-40853%22%5D%7D
    Example: {"PROD-1234":["PROD-2000","PROD-2003"],"PROD-2005":["PROD-2007"]}

  - `$filter[topicIds]` (array)
    An array of topic IDs. It is used to restrict search results to specific topics.

  - `articleCustomAdditionalAttributes` (string)
    One or more comma-separated names for article custom attributes defined by the user to be returned.

  - `$pagenum` (integer)
    Pagination parameter that specifies the page number of results to be returned. Used in conjunction with $pagesize.

  - `$pagesize` (integer)
    Pagination parameter that specifies the number of results per page. Used in conjunction with $pagenum.

## Path parameters:

  - `portalID` (string, required)
    The ID of the portal being accessed.A portal ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.
    Example: "PROD-1000"

## Response 200 fields (application/json):

  - `searchResults` (object, required)
    Top search results with relevance scores

  - `searchResults.article` (array)

  - `searchResults.article.id` (string, required)
    The ID of the Article.  An Article ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.
    Example: "PROD-2996"

  - `searchResults.article.name` (string, required)
    The name of the Article or source content.
    Example: "Fair Lending FAQs"

  - `searchResults.article.docType` (string, required)
    Format of the source document (HTML, DOCX, PPTX or PDF).
    Enum: "HTML", "DOCX", "PDF", "PPTX"

  - `searchResults.article.docName` (string)
    Name of the attachment, if an attachment was used as the source content.
    Example: "Lending FAQs"

  - `searchResults.article.source` (string, required)
    The source type.
    Enum: "eGain Article", "eGain Attachment"

  - `searchResults.article.customAttributes` (array)
    Custom attributes assigned to an article

  - `searchResults.article.customAttributes.name` (string)
    The custom attribute's name.
    Example: "loan_id"

  - `searchResults.article.customAttributes.value` (array)
    The custom attribute's values.
    Example: ["78391"]

  - `searchResults.article.customAttributes.type` (string)
    The custom attribute's type.
    Enum: "STRING", "INTEGER", "BOOLEAN", "DATETIME"

  - `searchResults.article.snippet` (string, required)
    A semantic snippet of the article content.
    Example: "What is fair lending..."

  - `searchResults.article.keywordSnippet` (string)
    A keyword search snippet of article content.
    Example: "What is fair lending..."

  - `searchResults.article.additionalSnippets` (array)
    An array of snippets belonging to the same article.

  - `searchResults.article.additionalSnippets.snippet` (string, required)
    A snippet of the article content.
    Example: "The following Banking FAQs..."

  - `searchResults.article.additionalSnippets.keywordSnippet` (string)
    A keyword snippet of the article content.
    Example: "The following Banking FAQs..."

  - `searchResults.article.additionalSnippets.relevanceScore` (number)
    Generated confidence score (0.0-1.0) for the snippet's relevance to the query.
    Example: 0.7

  - `searchResults.article.additionalSnippets.normalizedScore` (number, required)
    Score (0.0-1.0) normalized across all results, where the top result is 1.0 and the lowest is 0.0.
    Example: 0.9

  - `searchResults.article.additionalSnippetCount` (integer)
    Number of additional snippets.
    Example: 1

  - `searchResults.article.contextualSummary` (string)
    Contextual Summary generated as part of metadata for the chunk content.
    Example: "The summary of the lending FAQ..."

  - `searchResults.article.modifiedDate` (string)
    The date on which the Article was last modified.
    Example: "2025-01-28T19:53:58Z"

  - `searchResults.article.headerPath` (string)
    The header path of the snippet retrieved.
    Example: "FAQs"

  - `searchResults.article.topicBreadcrumb` (array, required)
    A list of topics from the root topic to this Article. There may be multiple paths.

  - `searchResults.article.topicBreadcrumb.topicSummary` (array)
    An instance of TopicSummary.

  - `searchResults.article.topicBreadcrumb.topicSummary.id` (string)
    The alphanumeric ID of the topic.A topic ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.
    Example: "PROD-1921"

  - `searchResults.article.topicBreadcrumb.topicSummary.name` (string)
    The name of the topic.
    Example: "Banking Regulations"

  - `searchResults.article.tagCategories` (array)
    An array of tag categories. Note that the total number of tag categories cannot exceed 20.

  - `searchResults.article.tagCategories.id` (string)
    Tag Category ID

  - `searchResults.article.tagCategories.tags` (array)

  - `searchResults.article.articleTypeAttributes` (object)
    The type of the Article and its attributes.

  - `searchResults.article.articleTypeAttributes.typeName` (string)
    Indicates the article category name.
    Example: "General"

  - `searchResults.article.articleTypeAttributes.articleTypeId` (string)
    The ID of the Article Type.
    Example: 243500000023393

  - `searchResults.article.relevanceScore` (number)
    Query-specific relevance score (0.0-1.0) that reflects how well the result matches the user query. This score is only available when a re-ranker is enabled and represents a direct relevance comparison between the query and the returned snippet.
    Example: 0.8

  - `searchResults.article.normalizedScore` (number, required)
    Relative ranking score (0.0-1.0) normalized across all returned results, based on a combination of BM25 and semantic similarity scores. This score indicates how a result ranks compared to others in the same response, not its absolute relevance to the query. As a result, a high score does not necessarily imply strong query relevance.
    Example: 0.9

  - `paginationInfo` (object)

  - `paginationInfo.count` (integer, required)
    The total number of pages.

  - `paginationInfo.pagenum` (integer, required)
    The page number requested. Page numbers start from 1.

  - `paginationInfo.pagesize` (integer, required)
    The number of objects requested per page. The maximum number of objects per page is 75.

  - `paginationInfo.link` (array)
    Can include the prev and next link.

  - `paginationInfo.link.rel` (string)
    Defines the relationship between a linked resource and the current object.For example: self, prev, next or an object name such as 'user', 'folder' etc.

  - `paginationInfo.link.href` (string)
    The URL that specifies the link's destination.

## Response 400 fields (application/json):

  - `code` (string, required)
    A string that follows the pattern {integer}-{integer}.

The first {integer} is the http status code.  This code as a whole is unique.
* For example, error codes "400-101" and "404-101" are distinctly different.

  - `developerMessage` (string, required)
    A summary of the error.

  - `details` (array)

  - `details.key` (string, required)

  - `details.value` (string)

  - `userMessage` (string)
    UI friendly messages are only supported by some APIs.  
   The client must explicitly request UI friendly messages by passing the X-egain-error-message=yes* header.

## Response 401 fields (application/json):

  - `code` (string, required)
    A string that follows the pattern {integer}-{integer}.

The first {integer} is the http status code.  This code as a whole is unique.
* For example, error codes "400-101" and "404-101" are distinctly different.

  - `developerMessage` (string, required)
    A summary of the error.

  - `details` (array)

  - `details.key` (string, required)

  - `details.value` (string)

  - `userMessage` (string)
    UI friendly messages are only supported by some APIs.  
   The client must explicitly request UI friendly messages by passing the X-egain-error-message=yes* header.

## Response 403 fields (application/json):

  - `code` (string, required)
    A string that follows the pattern {integer}-{integer}.

The first {integer} is the http status code.  This code as a whole is unique.
* For example, error codes "400-101" and "404-101" are distinctly different.

  - `developerMessage` (string, required)
    A summary of the error.

  - `details` (array)

  - `details.key` (string, required)

  - `details.value` (string)

  - `userMessage` (string)
    UI friendly messages are only supported by some APIs.  
   The client must explicitly request UI friendly messages by passing the X-egain-error-message=yes* header.

## Response 404 fields (application/json):

  - `code` (string, required)
    A string that follows the pattern {integer}-{integer}.

The first {integer} is the http status code.  This code as a whole is unique.
* For example, error codes "400-101" and "404-101" are distinctly different.

  - `developerMessage` (string, required)
    A summary of the error.

  - `details` (array)

  - `details.key` (string, required)

  - `details.value` (string)

  - `userMessage` (string)
    UI friendly messages are only supported by some APIs.  
   The client must explicitly request UI friendly messages by passing the X-egain-error-message=yes* header.

## Response 406 fields (application/json):

  - `code` (string, required)
    A string that follows the pattern {integer}-{integer}.

The first {integer} is the http status code.  This code as a whole is unique.
* For example, error codes "400-101" and "404-101" are distinctly different.

  - `developerMessage` (string, required)
    A summary of the error.

  - `details` (array)

  - `details.key` (string, required)

  - `details.value` (string)

  - `userMessage` (string)
    UI friendly messages are only supported by some APIs.  
   The client must explicitly request UI friendly messages by passing the X-egain-error-message=yes* header.

## Response 500 fields (application/json):

  - `code` (string, required)
    A string that follows the pattern {integer}-{integer}.

The first {integer} is the http status code.  This code as a whole is unique.
* For example, error codes "400-101" and "404-101" are distinctly different.

  - `developerMessage` (string, required)
    A summary of the error.

  - `details` (array)

  - `details.key` (string, required)

  - `details.value` (string)

  - `userMessage` (string)
    UI friendly messages are only supported by some APIs.  
   The client must explicitly request UI friendly messages by passing the X-egain-error-message=yes* header.


## Response 204 fields