openapi: 3.0.0
info:
  title: Search API
  version: '2.0'
servers:
  - url: https://cdn.yextapis.com/v2
paths:
  /accounts/{accountId}/search/autocomplete:
    get:
      operationId: autocomplete
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/v'
        - $ref: '#/components/parameters/experienceKey'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/autocompleteInput'
        - $ref: '#/components/parameters/autocompleteLimit'
        - $ref: '#/components/parameters/version'
      summary: 'Universal Search: Autocomplete'
      description: Retrieve a list of suggested queries across all verticals in the experience based on the characters already typed by the user. This API is meant to be hit after each keystroke.
      responses:
        '200':
          $ref: '#/components/responses/AutocompleteResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/search/query:
    get:
      operationId: query
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/v'
        - $ref: '#/components/parameters/experienceKey'
        - $ref: '#/components/parameters/queryLocale'
        - $ref: '#/components/parameters/requiredInput'
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/session_id'
        - $ref: '#/components/parameters/universalLimit'
        - $ref: '#/components/parameters/queryTrigger'
        - $ref: '#/components/parameters/context'
        - $ref: '#/components/parameters/referrerPageUrl'
        - $ref: '#/components/parameters/skipSpellCheck'
        - $ref: '#/components/parameters/restrictVerticals'
        - $ref: '#/components/parameters/ignoreQueryRules'
        - $ref: '#/components/parameters/queryId'
        - $ref: '#/components/parameters/source'
        - $ref: '#/components/parameters/jsLibVersion'
      summary: 'Universal Search: Query'
      description: |
        Search for entities across all verticals within a Search experience.  Modules are returned for all verticals with relevant entities. Further fine tuning and filtering of the results can then be done using the vertical query endpoint. A maximum of 50 verticals can be queried with this endpoint.

        In order prevent bot traffic from using Search API Capacity, you must integrate with the Search API from the front end of your application.  The Search API's Bot Detection feature requires the API to be called directly from the end-user's web browser.  If you must integrate with the Search API via another mechanism, all traffic will be charged against your search capacity and some features of Search Analytics, such as Search Terms and Search Term Clustering may not work.
      responses:
        '200':
          $ref: '#/components/responses/UniversalQueryResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/search/vertical/autocomplete:
    get:
      operationId: verticalAutocomplete
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/v'
        - $ref: '#/components/parameters/experienceKey'
        - $ref: '#/components/parameters/verticalKey'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/autocompleteInput'
        - $ref: '#/components/parameters/autocompleteLimit'
        - $ref: '#/components/parameters/version'
      summary: 'Vertical Search: Autocomplete'
      description: Retrieve a list of suggested queries for the selected vertical based on the characters already typed by the user or the most popular queries when no user input is given.
      responses:
        '200':
          $ref: '#/components/responses/AutocompleteResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/search/vertical/query:
    get:
      operationId: verticalQuery
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/v'
        - $ref: '#/components/parameters/experienceKey'
        - $ref: '#/components/parameters/verticalKey'
        - $ref: '#/components/parameters/queryLocale'
        - $ref: '#/components/parameters/verticalInput'
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/locationRadius'
        - $ref: '#/components/parameters/session_id'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/queryTrigger'
        - $ref: '#/components/parameters/context'
        - $ref: '#/components/parameters/referrerPageUrl'
        - $ref: '#/components/parameters/skipSpellCheck'
        - $ref: '#/components/parameters/Filters'
        - $ref: '#/components/parameters/FacetFilters'
        - $ref: '#/components/parameters/retrieveFacets'
        - $ref: '#/components/parameters/SortBys'
        - $ref: '#/components/parameters/ignoreQueryRules'
        - $ref: '#/components/parameters/queryId'
        - $ref: '#/components/parameters/source'
        - $ref: '#/components/parameters/jsLibVersion'
      summary: 'Vertical Search: Query'
      description: |
        Search for entities within the selected vertical.  Vertical query allows for fine tuning of the search using filters, facets and sorts passed in through the API.

        In order prevent bot traffic from using Search API Capacity, you must integrate with the Search API from the front end of your application.  The Search API's Bot Detection feature requires the API to be called directly from the end-user's web browser.  If you must integrate with the Search API via another mechanism, all traffic will be charged against your search capacity and some features of Search Analytics, such as Search Terms and Search Term Clustering may not work.
      responses:
        '200':
          $ref: '#/components/responses/VerticalQueryResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/search/filtersearch:
    get:
      operationId: filtersearch
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/v'
        - $ref: '#/components/parameters/experienceKey'
        - $ref: '#/components/parameters/filterSearchVerticalKey'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/requiredInput'
        - $ref: '#/components/parameters/SearchParameters'
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/excluded'
      summary: 'Vertical Search: Filter Search'
      description: Retrieve a list of potential filters that match the user's input up to that point.  This differs from query suggest by only returning the names of filters that can be searched rather than the broader corpus of suggested queries.
      responses:
        '200':
          $ref: '#/components/responses/FilterSearchResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/search/generateAnswer:
    post:
      operationId: generateAnswer
      summary: |
        Answer: Generate
      description: |
        Leverages large language models (LLMs) to deliver generated summaries based on search results.

        This endpoint works with the Universal/Vertical Search endpoint, which provides the search results for the LLM to analyze and generate direct answers.
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/v'
        - $ref: '#/components/parameters/experienceKey'
        - $ref: '#/components/parameters/queryLocale'
      requestBody:
        description: JSON object containing the search results and user query to generate an answer.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAnswerRequest'
      responses:
        '200':
          $ref: '#/components/responses/GenerateAnswerResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: query
    api-key:
      type: apiKey
      name: api-key
      in: header
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      schema:
        type: string
    v:
      name: v
      in: query
      required: true
      schema:
        type: string
      description: A date in `YYYYMMDD` format.
    experienceKey:
      name: experienceKey
      in: query
      required: true
      schema:
        type: string
      description: String key that uniquely identifies the Search experience.
    locale:
      name: locale
      in: query
      required: true
      schema:
        type: string
      description: The locale code of the experience (e.g. `en_GB`).
    autocompleteInput:
      name: input
      in: query
      required: false
      schema:
        type: string
      description: The partial search term from the user.
    autocompleteLimit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 10
        maximum: 100
        minimum: 1
      description: Number of autocomplete results to return.
    version:
      name: version
      in: query
      required: false
      schema:
        type: string
      description: The label or version number of the experience configuration to use. Label options are `STAGING` or `PRODUCTION`. `STAGING` uses the Latest version of the configuration. If omitted the `PRODUCTION` label will be used.
    queryLocale:
      name: locale
      in: query
      required: true
      schema:
        type: string
      description: The locale code of the experience (e.g. `en_GB`). Only returns entities that have an entity profile associated with this locale.
    requiredInput:
      name: input
      in: query
      required: true
      schema:
        type: string
      description: The search term of the user.
    location:
      name: location
      in: query
      required: false
      schema:
        type: string
      description: The user's location as a comma separated latitude and longitude (e.g. `"40.740957,-73.987565"`).
    session_id:
      name: session_id
      in: query
      required: false
      schema:
        type: string
      description: UUID used to track session state when cookies are blocked.
    universalLimit:
      name: limit
      in: query
      required: false
      schema:
        type: string
      description: JSON object specifying the limit for each vertical.  Each key is a vertical key and the value for each of those keys is a number 1-50 that denotes the limit for that vertical. This parameter should be provided as a URL-encoded string containing a JSON object.
    queryTrigger:
      name: queryTrigger
      in: query
      required: false
      schema:
        type: string
      description: |
        String value that is logged to analytics denoting the trigger for the query.
        Options include:
        * `suggest`, sent if the query is triggered from a spelling correction.
        * `initialize`, sent if the query is being triggered by a default initial search (in other words, the user did not enter query).
    context:
      name: context
      in: query
      required: false
      schema:
        type: string
      description: Context is an arbitrary JSON object that is passed to query rules to be used for triggering rules as well as passing data to those rules. This parameter should be provided as a URL-encoded string containing a JSON object.
    referrerPageUrl:
      name: referrerPageUrl
      in: query
      required: false
      schema:
        type: string
      description: The URL of the webpage that directed to the page this request was made from.
    skipSpellCheck:
      name: skipSpellCheck
      in: query
      required: false
      schema:
        type: boolean
      description: If true the query will skip spell checking.
    restrictVerticals:
      name: restrictVerticals
      in: query
      required: false
      schema:
        type: string
      description: A comma-separated list of verticals (e.g. `"people,locations"`). If specified, only results from these verticals will be returned.
    ignoreQueryRules:
      name: ignoreQueryRules
      in: query
      required: false
      schema:
        type: boolean
      description: When set to true, ignores any Query Rules that would otherwise affect the results. Defaults to false.
    queryId:
      name: queryId
      in: query
      required: false
      schema:
        type: string
      description: UUID of the query; recommended when moving through results, to associate multiple requests to the same query.
    source:
      name: source
      in: query
      required: false
      schema:
        type: string
      description: Indicates where the query is coming from (e.g. `"HOME_HEADER"` or `"TICKET_FORM"`). Can be used in Analytics reports via the `Integration Source` dimension. Defaults to `"STANDARD"`.
    jsLibVersion:
      name: jsLibVersion
      in: query
      required: false
      schema:
        type: string
      description: The version of the Search UI used for this request. Deprecated.
    verticalKey:
      name: verticalKey
      in: query
      required: true
      schema:
        type: string
      description: String key that uniquely identifies the vertical.
    verticalInput:
      name: input
      in: query
      required: false
      schema:
        type: string
      description: The search term of the user.
    locationRadius:
      name: locationRadius
      in: query
      required: false
      schema:
        type: string
      description: Radius (in meters) that should be applied to any location filter that does not already have an explicit radius.
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 10
        maximum: 50
      description: Number of results to return.
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 9949
        default: 0
      description: Number of results to skip. Used to move through results.
    Filters:
      name: filters
      in: query
      required: false
      schema:
        type: string
      description: |
        This parameter represents one or more filtering conditions that are applied to the set of entities that would otherwise be returned. This parameter should be provided as a URL-encoded string containing a JSON object.

        For example, if the filter JSON is `{"name":{"$eq":"John"}}`, then the filters param after URL-encoding will be: `filters=%7B%22name%22%3A%7B%22%24eq%22%3A%22John%22%7D%7D`

        **Basic Filter Structure**

        The filter object at its core consists of a *matcher*, a *field*, and an *argument*.

        For example, in the following filter JSON:

        ```
        {
          "name":{
            "$eq":"John"
          }
        }
        ```

        `$eq` is the *matcher*, or filtering operation (equals, in this example),

        `name` is the *field* being filtered by, and

        `John` is *value* to be matched against.

        **Combining Multiple Filters**

        Multiple filters can be combined to form a conjunction (AND) of disjunctions (ORs) using the *combinators* `$and` and `$or`.  For example:
        ```
        {
          "$and": [
            {
              "$or": [
                {
                  "firstName": {
                    "$eq": "Jane"
                  }
                },
                {
                  "firstName": {
                    "$eq": "John"
                  }
                }
              ]
            },
            {
              "lastName": {
                "$eq": "Smith"
              }
            }
          ]
        }
        ```
        Any filter that is the only item in its respective combinator may omit the combinator as is done with the lastName above.

        **Filter Negation**

        Certain filter types may be negated. For example:

        ```
        {
          "$not": {
            "name": {
              "$eq": "John"
            }
          }
        }
        ```

        This can also be written more simply with a `!` in the `$eq` parameter. The following filter would have the same effect:

        ```
        {
          "name":{
            "!$eq":"John"
          }
        }
        ```

        **TEXT**

        The `TEXT` filter type is supported for text fields. (e.g., **`name`**, **`countryCode`**)

        <table style="width:100%">
          <tr>
            <th>Matcher</th>
            <th>Details</th>
          </tr>
          <tr>
            <th>$eq (equals)</th>
            <th>

            {
              "countryCode":{
                "$eq":"US"
              }
            },
            {
              "countryCode":{
                "!$eq":"US"
              }
            }

          Supports negation. Case insensitive.
          </tr>
          <tr>
        </table>

        **BOOLEAN**


        The BOOLEAN filter type is supported for boolean fields and Yes / No custom fields.
        <table style="width:100%">
          <tr>
            <th>Matcher</th>
            <th>Details</th>
          </tr>
          <tr>
            <th>$eq</th>
            <th>

            {
              "isFreeEvent": {
                "$eq": true
              }
            }

          For booleans, the filter takes a boolean value, not a string.
          Supports negation.
          </tr>
        </table>

        **OPTION**

        The OPTION filter type is supported for option custom fields and fields that have a predetermined list of valid values.

         *e.g., **`eventStatus`**, **`gender`**, `SINGLE_OPTION` and `MULTI_OPTION` types of custom fields.*

        <table style="width:100%">
          <tr>
            <th>Matcher</th>
            <th>Details</th>
          </tr>
          <tr>
            <th>$eq</th>
            <th>

          Matching is case insensitive and insensitive to consecutive whitespace.

          e.g., "XYZ 123" matches "xyz       123"

            {
              "eventStatus": {
                "$eq": "SCHEDULED"
              }
            }
        </table>

        **INTEGER, FLOAT, DATE, DATETIME, and TIME**

        These filter types are strictly ordered -- therefore, they support the following matchers:
        - Equals
        - Less Than / Less Than or Equal To
        - Greater Than / Greater Than or Equal To

        <table style="width:100%">
          <tr>
            <th>Matcher</th>
            <th>Details</th>
          </tr>
          <tr>
            <th>$eq</th>
            <th>

          Equals

            {
              "ageRange.maxValue": {
                "$eq": "80"
              }
            }

          Supports negation.

          </tr>
          <tr>
            <th>$lt</th>
            <th>

          Less than

            {
              "time.start": {
                "$lt": "2018-08-28T05:56"
              }
            }

          </tr>
          <tr>
            <th>$gt</th>
            <th>

          Greater than

            {
              "ageRange.maxValue": {
                "$gt": "50"
              }
            }

          </tr>
          <tr>
            <th>$le</th>
            <th>

          Less than or equal to

            {
              "ageRange.maxValue": {
                "$le": "40"
              }
            }

          </tr>
          <tr>
            <th>$ge</th>
            <th>

          Greater than or equal to

            {
              "time.end": {
                "$ge":  "2018-08-28T05:56"
              }
            }

          </tr>
          <tr>
            <th>$between</th>
            <th>

          An array that must contain exactly two elements with which the result is between.

            {
              "time.end": {
                "$between":  ["2018-08-28T05:56", "2018-08-29T05:56"]
              }
            }

          </tr>
          <tr>
            <th>Combinations</th>
            <th>

          In addition to between, it is possible to combine multiple matchers for a result similar to an "and" operation:

            {
              "ageRange.maxValue" : {
                "$gt" : 10,
                "$lt": 20
              }
            }

          </tr>
        </table>
    FacetFilters:
      name: facetFilters
      in: query
      required: false
      schema:
        type: string
      description: |
        This parameter represents the state of the currently checked facet options. This parameter should be provided as a URL-encoded string containing a JSON object.

        The JSON object contains a key for each facet category that has a checked facet option.  The value for each of these keys is an array of Filter objects that describe the filter that is applied by the facet option.

        At the moment, facet options only support `$eq`.

        For example, if `Engineering` was checked under the `Category` facet and `Chicago` and `New York` are checked under the `Job Location` facet, the `facetFilters` would look like:
        ```
        {
          "c_jobCategory": [
            {
              "c_jobCategory": {
                "$eq": "Engineering"
              }
            }
          ],
          "c_jobLocation": [
            {
              "c_jobLocation": {
                "$eq": "Chicago"
              }
            },
            {
              "c_jobLocation": {
                "$eq": "New York"
              }
            }
          ]
        }
        ```
    retrieveFacets:
      name: retrieveFacets
      in: query
      required: false
      schema:
        type: boolean
      description: Whether facets should be computed for this vertical query.
    SortBys:
      name: sortBys
      in: query
      required: false
      schema:
        type: string
      description: |
        This parameter overrides the sort options that are configured on the experience configuration.  This parameter should be provided as a URL-encoded string containing a JSON array.

        The input is a JSON array containing each of the sort options in the order in which they should be applied.

        Each sort options must contain a `type`

        <table style="width:100%">
          <tr>
            <th>Type</th>
            <th>Details</th>
          </tr>
          <tr>
            <th>RELEVANCE</th>
            <th>Sorts based on relevance according to the algorithm and, when relevant, location bias</th>
          </tr>
          <tr>
            <th>ENTITY_DISTANCE</th>
            <th>Sorts based on entity distance alone</th>
          </tr>
          <tr>
            <th>FIELD</th>
            <th>sorts based on a field with the direction specified</th>
          </tr>
        </table>

        </br>

        If the `type` is `FIELD` the sort options must also specify `field` which is the api name of the field to sort on.

        Finally, if the `type` is `FIELD` the sort options must also specify the `direction`.

        <table style="width:100%">
          <tr>
            <th>Direction</th>
            <th>Details</th>
          </tr>
          <tr>
            <th>ASC</th>
            <th>Sorts in ascending order.  For numbers this is low to high. For text this is alphabetical.  For dates this is chronological order.</th>
          </tr>
          <tr>
            <th>DESC</th>
            <th>Sorts in ascending order.  For numbers this is high to low. For text this is reverse alphabetical.  For dates this is reverse chronological order.</th>
          </tr>
        </table>

        </br>

        **Examples**
        ```
        [
          {
            "type": "FIELD",
            "direction": "ASC",
            "field": "startDate"
          },
          {
            "type": "RELEVANCE",
            "direction": "ASC"
          }
        ]
        ```
    filterSearchVerticalKey:
      name: verticalKey
      in: query
      required: true
      schema:
        type: string
      description: String key that uniquely identifies the vertical to scope the filter search request to.
    SearchParameters:
      name: search_parameters
      in: query
      required: true
      schema:
        type: string
      description: |
        This parameter represents the parameters that should be used for filter search. This parameter should be provided as a URL-encoded string containing a JSON object.

        Filter search uses the user's input string to find a set of existing filters that match the user's input query for the fields provided in the parameters.

        The JSON object must have a `fields` property made up of a list of `FilterField` objects that have the following properties:

        <table style="width:100%">
          <tr>
            <th>Property</th>
            <th>Details</th>
          </tr>
          <tr>
            <th>fieldId</th>
            <th>The api name of the field.</th>
          </tr>
          <tr>
            <th>entityTypeId</th>
            <th>The api name for the entity type the filter belongs to.</th>
          </tr>
          <tr>
            <th>shouldFetchEntities</th>
            <th>Optional boolean.  If true, entities matching each filter will be returned inline with the filter.</th>
          </tr>
        </table>

        </br>

        Additionally, there is an optional boolean property `sectioned`.  If set to true, the matching filters will be returned in a separate section per field.  By default, they are all returned in the same section.
    excluded:
      name: excluded
      in: query
      required: false
      schema:
        type: string
      description: |
        This parameter represents any values which should not be returned. This parameter should be provided as a URL-encoded string containing a JSON array, where each entry of the array is a JSON object representing a field and an excluded value for that field. For example:
        ```
        [
          {
            "name": {
              "$eq": "John"
            }
          },
          {
            "c_jobCategory": {
              "$eq": "Engineering"
            }
          }
        ]
        ```
  responses:
    AutocompleteResponse:
      description: Autocomplete Request Response
      content:
        application/json:
          schema:
            title: AutocompleteResponse
            type: object
            properties:
              input:
                type: object
                properties:
                  value:
                    type: string
                    description: |
                      The exact user input that triggered the autocomplete.
                  queryIntents:
                    type: array
                    description: |
                      List of query intents that the input has been tagged with.
                    items:
                      type: string
                      description: |
                        Intent that was derived from the user's input.
              results:
                type: array
                description: |
                  The list of autocomplete results computed from the user's input.
                items:
                  type: object
                  description: |
                    An individual autocomplete match.
                  properties:
                    value:
                      type: string
                      description: |
                        The plain text version of the autocomplete result.
                    matchedSubstrings:
                      type: array
                      description: |
                        The list of matched substrings within the value to highlight.
                      items:
                        type: object
                        description: |
                          Highlight information for the string autocomplete value.
                        properties:
                          offsets:
                            type: integer
                            description: |
                              The zero indexed offset from the start of the value where the highlight starts.
                          length:
                            type: integer
                            description: |
                              The length of the highlight.
                    queryIntents:
                      type: array
                      description: |
                        List of query intents that the input has been tagged with.
                      items:
                        type: string
                        description: |
                          Intent that was derived from the user's input.
                    verticalKeys:
                      type: array
                      description: |
                        List of verticals that the autocomplete result is derived from. For results coming from universal search, this field will be blank.
                      items:
                        type: string
                        description: |
                          A single vertical represented in the autocomplete result.
          example:
            meta:
              uuid: 4f72b877-e2d0-4de4-9324-b9cf2c03e1a0
              errors: []
            response:
              input:
                value: yex
                queryIntents: []
              results:
                - value: Yext Listings
                  matchedSubstrings:
                    - offset: 0
                      length: 3
                  verticalKeys:
                    - products
                - value: Yext Search
                  matchedSubstrings:
                    - offset: 0
                      length: 3
                  verticalKeys:
                    - products
    ErrorResponse:
      description: Error Response
      content:
        application/json:
          schema:
            title: ErrorResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMetaWithError'
              response:
                type: object
    UniversalQueryResponse:
      description: Universal Query Response
      content:
        application/json:
          schema:
            title: UniversalQueryResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                properties:
                  businessId:
                    $ref: '#/components/schemas/businessId'
                  queryId:
                    $ref: '#/components/schemas/queryId'
                  modules:
                    $ref: '#/components/schemas/Modules'
                  failedVerticals:
                    $ref: '#/components/schemas/FailedVerticals'
                  directAnswer:
                    $ref: '#/components/schemas/DirectAnswer'
                  spellCheck:
                    $ref: '#/components/schemas/SpellCheck'
                  locationBias:
                    $ref: '#/components/schemas/LocationBias'
    VerticalQueryResponse:
      description: Vertical Query Response
      content:
        application/json:
          schema:
            title: VerticalQueryResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                properties:
                  businessId:
                    $ref: '#/components/schemas/businessId'
                  queryId:
                    $ref: '#/components/schemas/queryId'
                  resultsCount:
                    $ref: '#/components/schemas/resultCount'
                  results:
                    $ref: '#/components/schemas/Results'
                  appliedQueryFilters:
                    $ref: '#/components/schemas/AppliedQueryFilters'
                  facets:
                    type: array
                    description: Contextual facets that contain metadata about the facet as well as the full facet.
                    items:
                      $ref: '#/components/schemas/Facets'
                  searchIntents:
                    $ref: '#/components/schemas/SearchIntents'
                  source:
                    type: string
                    description: Identifier for the backend source of the response.
                    example: KNOWLEDGE_MANAGER
                  directAnswer:
                    $ref: '#/components/schemas/DirectAnswer'
                  alternativeVerticals:
                    type: object
                    description: Response information from running this query on other verticals.
                    properties:
                      modules:
                        $ref: '#/components/schemas/Modules'
                      failedVerticals:
                        $ref: '#/components/schemas/FailedVerticals'
                  spellCheck:
                    $ref: '#/components/schemas/SpellCheck'
                  locationBias:
                    $ref: '#/components/schemas/LocationBias'
                  allResultsForVertical:
                    type: object
                    description: All results for this vertical.
                    properties:
                      businessId:
                        $ref: '#/components/schemas/businessId'
                      queryId:
                        $ref: '#/components/schemas/queryId'
                      resultsCount:
                        $ref: '#/components/schemas/resultCount'
                      results:
                        $ref: '#/components/schemas/Results'
                      facets:
                        type: array
                        description: Contextual facets that contain metadata about the facet as well as the full facet.
                        items:
                          $ref: '#/components/schemas/Facets'
                      searchIntents:
                        $ref: '#/components/schemas/SearchIntents'
    FilterSearchResponse:
      description: Filter Search Response
      content:
        application/json:
          schema:
            title: FilterSearchResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                properties:
                  businessId:
                    $ref: '#/components/schemas/businessId'
                  sections:
                    type: array
                    description: |
                      The set of field names being queried, and their respective results for the current query
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                          description: |
                            The display name of the field being queried, can be used in a UI to distinguish one section from another
                        results:
                          type: array
                          description: |
                            The set of matches for the current query
                          items:
                            type: object
                            properties:
                              key:
                                type: string
                                description: |
                                  The API name of a field with a match for the current query
                              value:
                                type: string
                                description: |
                                  The display name of the field value with a match for the current query
                              filter:
                                $ref: '#/components/schemas/filter'
                              matchedSubstrings:
                                type: array
                                description: |
                                  A set of offsets that represent the portion of the "value" that is a match for the current query
                                items:
                                  type: object
                                  properties:
                                    offset:
                                      type: integer
                                      description: |
                                        In the "value", the number of characters between the beginning of the string and the start of the match for the current query
                                    length:
                                      type: integer
                                      description: |
                                        In the "value", the number of characters from the offset that represents the end of the match for the current query
                              relatedItem:
                                type: object
                                description: |
                                  If a unique entity returns for the current query, the full entity object
                  failedVerticals:
                    $ref: '#/components/schemas/FailedVerticals'
                  queryId:
                    $ref: '#/components/schemas/queryId'
    GenerateAnswerResponse:
      description: Generate Answer Response
      content:
        application/json:
          schema:
            title: GenerateAnswerResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                properties:
                  directAnswer:
                    type: string
                    description: The direct answer for the query.
                  resultStatus:
                    type: string
                    description: The status of the result.
                  citations:
                    type: array
                    description: The list of entity IDs that were used to generate the answer.
                    items:
                      type: string
                      description: An ID of an entity that was used to generate the answer.
  schemas:
    ResponseMeta:
      type: object
      properties:
        uuid:
          type: string
          example: 4f72b877-e2d0-4de4-9324-b9cf2c03e1a0
          description: Unique ID for this request / response.
    ResponseError:
      type: object
      properties:
        name:
          type: string
        code:
          type: integer
          description: |
            Code that uniquely identifies the error or warning.
        type:
          type: string
          enum:
            - FATAL_ERROR
            - NON_FATAL_ERROR
            - WARNING
        message:
          type: string
          description: Message explaining the problem.
    ResponseMetaWithError:
      allOf:
        - $ref: '#/components/schemas/ResponseMeta'
        - type: object
          properties:
            errors:
              type: array
              description: List of errors and warnings.
              items:
                $ref: '#/components/schemas/ResponseError'
    businessId:
      type: integer
      description: ID of the account associated with this Search experience
    queryId:
      type: string
      description: UUID for the query
    verticalConfigId:
      type: string
      description: String key that uniquely identifies the vertical.
    resultCount:
      type: integer
      description: |
        The number of entities within the vertical that are relevant to the user's query.
    Entity:
      type: object
      properties:
        data:
          type: object
          description: |
            The data containing the main content of the entity. The format of the data is dependent on the entity type.
        highlightedFields:
          type: object
          description: |
            A map from fieldId to highlighted element.
        distance:
          type: integer
          description: |
            The distance in meters between the entity and the query's location bias.
        distanceFromFilter:
          type: integer
          description: |
            The distance in meters between the entity and the filter applied to the query.
    Results:
      type: array
      description: |
        The individual entity results that contain metadata about the entity as well as the fully rendered profiles.
      items:
        $ref: '#/components/schemas/Entity'
    filter:
      type: object
      description: |
        The filter, in the filter format, that was applied.
        <br><br>
        For example: `"c_exampleFieldId": { $eq": "Search" }`
      example: |
        c_exampleFieldId: { $eq": "Search" }
    AppliedQueryFilters:
      type: array
      description: A list of the filters that were inferred from the user's query and applied at search time.
      items:
        type: object
        properties:
          displayKey:
            type: string
            description: The display name of the field to which the filter belongs.
          displayValue:
            type: string
            description: The value of the filter.
          filter:
            $ref: '#/components/schemas/filter'
          type:
            type: string
            enum:
              - FIELD_VALUE
              - PLACE
              - INTENT
          details:
            type: object
            description: |
              Object containing additional details relevant to the filter such as additional details about the place for `PLACE` type filters. The format of the data is dependent on the filter type.
    Module:
      type: object
      description: The results and metadata pertaining to a single vertical relevant to the user's query.
      properties:
        verticalConfigId:
          $ref: '#/components/schemas/verticalConfigId'
        resultCount:
          $ref: '#/components/schemas/resultCount'
        encodedState:
          type: string
          description: Deprecated.
        results:
          $ref: '#/components/schemas/Results'
        appliedQueryFilters:
          $ref: '#/components/schemas/AppliedQueryFilters'
    Modules:
      type: array
      description: List of results for each vertical that was relevant to the query, returned in the order of relevance.
      items:
        $ref: '#/components/schemas/Module'
    FailedVertical:
      type: object
      properties:
        verticalConfigId:
          $ref: '#/components/schemas/verticalConfigId'
        errorType:
          type: string
          description: |
            An identifier for the type of error causing the failure.
          enum:
            - TIMEOUT
            - BACKEND_ERROR
            - INVALID_CONFIG
            - INVALID_QUERY
        details:
          type: object
          properties:
            responseCode:
              type: integer
              description: |
                An HTTP response status code indicating the completion status of the request.
            description:
              type: string
              description: Message explaining the error.
        queryDurationMillis:
          type: integer
          description: |
            A measure of query duration, recorded in milliseconds.
    FailedVerticals:
      type: array
      description: |
        Contains error information when one or more verticals fail to return results.
      items:
        $ref: '#/components/schemas/FailedVertical'
    DirectAnswer:
      type: object
      description: |
        Information that is estimated to directly answer the question of the query.
      properties:
        type:
          type: string
          description: |
            Type of the direct answer, such as `FIELD_VALUE` or `FEATURED_SNIPPET`.
        answer:
          type: object
          description: |
            The data containing the main content of the direct answer. The format of the data is dependent on the direct answer type.
        relatedItem:
          type: object
          description: |
            An optional item that is related to the direct answer. For Knowledge Manager verticals, related items will typically be entities.
          properties:
            verticalConfigId:
              $ref: '#/components/schemas/verticalConfigId'
            data:
              type: object
              description: |
                The data of the related item, which should be in the same shape (with possibly extra fields) as an item that appears in a section of results from the same vertical in universal search.
    HighlightedValue:
      type: object
      description: |
        Highlighting instructions for a field value, containing the original value of the field and all sections of the value that should be highlighted.
      properties:
        value:
          type: string
          description: |
            The original value of the field.
        matchedSubstrings:
          type: array
          description: |
            The list of matched substrings within the value to highlight.
          items:
            type: object
            description: |
              Highlight information for the string autocomplete value.
            properties:
              offsets:
                type: integer
                description: |
                  The zero indexed offset from the start of the value where the highlight starts.
              length:
                type: integer
                description: |
                  The length of the highlight.
    SpellCheck:
      type: object
      description: SpellCheck information that may correct the user's query.
      properties:
        originalQuery:
          type: string
          description: The unedited, original query from the request.
        correctedQuery:
          $ref: '#/components/schemas/HighlightedValue'
        type:
          type: string
          description: |
            The type of SpellCheck suggestion.
            <br><br>
            `SUGGEST` is often used for "Did you mean..."
            <br>
            `AUTOCORRECT` is often used for "Showing results for ... instead of ..."
            <br>
            `COMBINE` is often used for "Including results for ..."
            <br><br>
          enum:
            - SUGGEST
            - AUTOCORRECT
            - COMBINE
    LocationBias:
      type: object
      description: Information about geographical location biases used in the search.
      properties:
        latitude:
          type: number
          description: The geographic coordinate, latitude, used to bias the search.
          example: 41.7828
        longitude:
          type: number
          description: The geographic coordinate, latitude, used to bias the search.
          example: -87.8781
        locationDisplayName:
          type: string
          description: The display name of the location.
          example: Countryside, Illinois, United States
        accuracy:
          type: string
          description: |
            The accuracy of the location bias used for the search.
            <br><br>
            `DEVICE` is based on the user's device (passed in via the request param)
            <br>
            `IP` is based on the request's IP
            <br>
          enum:
            - IP
            - DEVICE
            - UNKNOWN
    Facets:
      type: object
      properties:
        fieldId:
          type: string
          description: The field identifier for the field being searched.
        displayName:
          type: string
          description: The display name for the field being searched.
        options:
          type: array
          items:
            type: object
            properties:
              displayName:
                type: string
                description: The display name for the Facet option.
              count:
                type: integer
                description: The number of entities within the vertical that are relevant to this Facet option.
              isSelected:
                type: boolean
                description: A boolean indicator of whether this Facet option was used to filter results in the response.
              filter:
                $ref: '#/components/schemas/filter'
    SearchIntents:
      type: array
      description: |
        Items in array each represent a particular intent expressed in the user's query. Example: `NEAR_ME`
      items:
        type: string
    GenerateAnswerRequest:
      type: object
      required:
        - searchId
        - searchTerm
        - results
      properties:
        searchId:
          type: string
          description: ID of the search associated to the results.
        searchTerm:
          type: string
          description: The search term that was used to generate results.
        results:
          oneOf:
            - $ref: '#/components/schemas/Module'
            - type: object
              properties:
                verticals:
                  $ref: '#/components/schemas/Modules'
security:
  - api_key: []
  - api-key: []
tags:
  - name: Search API