# 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

## Path parameters:

  - `portalID` (string, required)
    The ID of the portal being accessed.<br><br>A portal ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.

## Query parameters:

  - `q` (string, required)
    The search query string. The string must be escaped as required by the URL syntax rules.

  - `$filter[userProfileID]` (string)
    The ID of the user profile.

  - `$lang` (string, required)
    The language used for a resource. Resources available in different languages may differ from each other.

  - `$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

  - `$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.

## 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.
    Enum: "HTML", "DOCX", "PDF", "PPTX", "XLSX", "XLSM", "XLSB"

  - `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.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.additionalSnippets.name` (string, required)
    The name of the Article or source content.
    Example: Fair Lending FAQs

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

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

  - `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` (any)
    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.