Overview

1. LipiSearch

LipiSearch is a high-performance, white-label search solution designed specifically for developers and product teams. Built on Apache Solr, it provides enterprise-grade search capabilities that can be seamlessly integrated into your applications with minimal configuration.

LipiSearch delivers blazing fast search results even with millions of records.

LipiSearch is a complete search infrastructure that handles everything from data ingestion to complex search queries. It’s designed to scale with your business while maintaining consistent performance.

1.1. Key Features

Feature Description

Enterprise-Grade Performance

Built on Apache Solr with optimizations for speed and scalability. Handles millions of records with sub-second response times.

Advanced Search Capabilities

Full-text search, faceted navigation, filtering, auto-suggestions, spell correction and complex query support.

Data Synchronization

Push data updates via REST APIs or schedule batch imports from databases.

Multi-Language Support

Optimized for global applications with support for multiple languages.

Role-Based Security

Granular API access control with separate tokens for Admin, Configuration, Data Management and Search operations.

Complete White-Label Solution

Zero LipiSearch branding. Fully customizable to match your brand identity and user experience.

Developer-First Design

RESTful JSON APIs with comprehensive documentation, code examples and interactive testing capabilities.

1.2. Use Cases

LipiSearch excels in scenarios requiring fast, accurate search across large datasets.

Use Case Description

E-commerce Platforms

Product search with filters, faceted navigation, price ranges and inventory management.

Business Intelligence Dashboards

Analytics, reporting and data exploration with aggregations and drill-down capabilities.

Data Analytics Platforms

Large-scale data exploration, filtering and visualization with statistical aggregations.

1.3. Why LipiSearch?

  • Performance: Blazing fast search across millions of records

  • Scalability: Handles growing data volumes without performance degradation

  • Flexibility: Customizable to match your exact requirements

  • Reliability: Enterprise-grade stability with 99.9% uptime

  • Support: Comprehensive documentation and developer support

2. Quick Link

2.1. Interactive Demo

Experience LipiSearch capabilities with our interactive demo featuring real-world datasets and search scenarios.

Try the LipiSearch Interactive Demo to see features in action.
Demo Includes

  • E-commerce Search: Product catalog with filters, facets and autocomplete

  • Content Search: Document search with highlighting and suggestions

  • Analytics Dashboard: Real-time aggregations and drill-down capabilities

2.2. Admin Panel

The LipiSearch Admin Panel provides a web-based interface for testing and managing different collections.

Access the LipiSearch Admin Panel for collection management.
Start with Panel

  1. Navigate to the Admin Panel URL

  2. Select your collection from the dropdown

  3. Use the query as is or adjust to test search functionality

3. Getting Started

This section will help you get up and running with LipiSearch APIs quickly.

3.1. Prerequisites

Before you begin, ensure you have:

  1. A valid LipiSearch license and configuration

  2. API access credentials (tokens)

  3. Basic understanding of REST APIs and JSON

  4. Your data source ready for indexing

3.2. Authentication

LipiSearch uses token-based authentication. All API requests require a valid token in the header.

Authorization: Bearer {Token}

3.2.1. Base URL

All API endpoints are relative to your LipiSearch instance.

https://lipisearch.your-domain.com/api
Feel free to explore LipiSearch through various APIs (Search, Data & Admin).

APIs (Search)

LipiSearch provides a comprehensive set of search APIs designed to handle various search scenarios. Each API is optimized for specific use cases while maintaining consistent performance and response formats.

Search Types

LipiSearch offers 5 specialized search APIs, each designed for specific functionality:

API Type Description & Use Cases

Query Search

The primary search API for full-text search, filtering and faceted navigation. Supports complex queries, sorting, highlighting and pagination. Ideal for product catalogs, content search and data exploration.

Group Search

Specialized API for searching within predefined groups or categories. Enables quick categorization and group-based filtering. Perfect for hierarchical data structures and category-based navigation.

Auto Suggest

Real-time text completion and suggestion API. Provides intelligent suggestions as users type, improving search experience and discoverability. Essential for search-as-you-type interfaces.

Spell Correction

Intelligent spelling correction based on your indexed data. Automatically suggests corrections for misspelled search terms, improving search accuracy and user experience.

Combined Search

API that combines multiple search operations into a single request. Executes searches in parallel for optimal performance. Reduces network overhead and improves response times.
Common Features

All search APIs share these common capabilities:

  • Authentication: Token-based security

  • Pagination: Configurable result limits and offsets

  • Error Handling: Consistent error response format

  • Performance: Sub-second response times

  • Scalability: Handles millions of records efficiently

Best Practices

  • Use the appropriate API for your use case

  • Implement proper error handling

  • Use pagination for large result sets

  • Combine multiple operations when possible

4. Query

Table 1. Params
Param Default Example Description

ref

N/A

"q1"

Reference id/key/string of request going back in response as is. It has nothing to do with the search. It helps multiple requests from caller to track each of them correctly.

text

N/A

"Bud"

Standard text search which applies to various fields by default

searchFields

N/A

"name^2 company short_desc^0.5"

Each field’s importance can be boosted differently for the text search. Given example boosts matches in name with double multiplier, keeps company at default weight and lowers the importance of short_desc by half.

quickSearch

false

true

Standard text search which applies to selected fields to support a faster result

query

N/A

"name:Vineyards"

The query search feature enables field-level searches through direct Solr queries

sort

N/A

"gluten_free desc,name asc"

The sort enables manual sorting on response docs

fuzzy

0

1

Fuzzy search allows values 0 (default), 1 or 2. Adds number of character fuzziness during search. Applies to "text" and "search" both having string values. (Example: Search of "roam" with fuzzy=1, will match terms like roams & foam. It will also match the word "roam" itself.)

filters

N/A

{"category_s":"Beer","sugar_free": true}

Filters the results with additional query by specific fields

join

N/A

{"collection": "gls-price","from": "product_id","to": "product_id","query": "id:(3913_10229 9267_10229) AND inventory:true"}

To join from another collection in Solr, specify the

collection → provide collection name

from → from field

to → to field

query → provide Join Clause

facetLimit

5

10

Number of top buckets required within each facet

facets

N/A

["brand_s","type_s"]

Facet fields to have positive counts of the values

highlighting

N/A

["name","short_desc"]

With highlights, now json renders more readable format with colors

facetSorts

N/A

{ "region_s":"index asc", "item_type_s":"count asc" }

Applies sorting on facets: defaults to count desc. Supports sorting — e.g., count asc for ascending count, or index desc for descending value.

statFacets

N/A

{"avgPrice": "avg(price)"}

Used for statistical calculations on fields within your dataset. (Example: min(price) ,max(price) ,sum(price), avg(price), count(price), percentile(field, 90), stddev(field),median(price))

nestedFacets

N/A

{ "fuzzy": "0", "start": 0, "rows": 0, "filters": null, "nestedFacets": { "country_s": { "facetLimit": 5, "nestedFacetSort": "yFacet", "statFacets": { "yFacet": "sum(unit_price)" }, "nestedFacets": { "item_type_s": { "facetLimit": 5, "nestedFacetSort": "yFacet", "statFacets": { "yFacet": "sum(unit_price)" } } } } } }

Nested facets generated multi-dimension results with combinations of "facets" and "statFacets". Extremely useful for dashboards and visualisations.

nestedFacetSort

N/A

avg_unit_price asc OR count desc OR count asc OR index desc OR index asc

Defines sorting behavior for nested facets. Defaults to descending count (count desc). Supports custom sorting — for example, avg_unit_price desc for descending order, or avg_unit_price asc for ascending order.

rangeFacets

N/A

[{ "prices": { "field": "price", "start": 0, "end": 100, "gap": 10 } }]

Used for RangeFacets on fields within your dataset. (To get the RangeFacets specify the

rangeFacets → Request attribute used to define range facets

prices → The field that will return the response for range facets.

field → The field on which the range facet will be applied.

start → The starting value of the range.

end → The ending value of the range.

gap → The interval (or gap) between the values in the range. This is optional and if not specified, the default value is calculated as (end - start) )

start

0

11

Need record from

rows

10

20

Number of records (Pagination size)

nested

false

true

If nested is true, response includes child as part of parent. Child docs always remains parallel to parent as separate docs.

return

All Fields

["id", "sku", "name", "image", "brand"]

Returns all fields in response. If specified, returns only those specified fields.
Multi-word effect can be applicable in "filters & text" by escaping double quote. {"brand_s": "\"Johny Walker\""}
In "facets", use "_s" postfix for field having single text value (not "list" value). It gives non-tokenised proper as-is full multi-words value in filters.
+ - && || ! ( ) { } [ ] ^ " ~ * ? : / characters are reserved and not supported directly in search: To include any of these characters in the search text, prefix them with a backslash (\) to escape them.

4.1. Special Cases

4.1.1. Escape

Problem

If "starts with" queries have more than one word, they give unexpected results. For example, "…​:Bud Li*" gives results starting with "Li…​" because Solr is a tokenized mechanism that treats "Bud" and "Li" as separate tokens.

Solution

Simply escape all spaces in "starts with" queries using backslashes to prevent tokenization. This tells Solr to treat the phrase as a single token.

Table 2. Examples
Query Type Query Result

Starts with - Without escape

"…​:Bud Li*"

Matches anything starting with "Li" (e.g., "Light", "Lite", "Lincoln") because Solr tokenizes "Bud Li" into separate tokens.

Starts with - With escape

"…​:Bud\\ Li*"

Matches only results starting with "Bud Li" (e.g., "Bud Light", "Bud Lite") because the escaped space prevents tokenization.

Multi-word in filters

{"brand_s": "\"Johny Walker\""}

Matches exact multi-word phrase "Johny Walker" in filters. Escaped double quotes ensure the phrase is treated as a single token.

Multi-word in text

"text": "\"Johny Walker\""

Matches exact multi-word phrase "Johny Walker" in text search. Escaped double quotes ensure the phrase is treated as a single token.

4.1.2. Word Boosting

Problem

First word in search may not have higher search priority. For example, searching "Bud Lite" may return "Miller Lite" first instead of "Bud Light" because a four-character match ("Lite" matches in "Miller Lite") gives higher priority than a three-character match ("Bud" matches in "Bud Light").

Solution

Use the caret (^) notation to boost specific words in your search query. It gives higher priority to the boosted word/s. The number after caret (^) indicates the boost factor.

Table 3. Examples
Boost Search Query Description

Natural scoring (no boost)

"Bud Lite"

Uses natural scoring without any word preference. Results are ranked based on character match relevance.

Single word boost

"Bud^2 Lite"

Gives preference to "Bud" with a boost factor of 2. It prioritizes results containing "Bud" over "Lite" alone.

Multiple words boost

"Bud Light^3 Ice^2"

Boosts "Light" with factor 3 and "Ice" with factor 2. Higher numbers indicate higher priority. Results matching "Light" will have highest priority, followed by "Ice", then "Bud".

4.1.3. Fuzzy

Problem

Searching "henesy" with fuzzy=2 returns "honest" as the first result and "hennessy" as the second result, even though "hennessy" is phonetically closer to "henesy".

Understanding

  • Fuzzy search works based on pure character count differences, not phonetics or visual similarity.

  • Fuzzy search works on pure character count differences (Levenshtein distance). It calculates how many characters need to be changed, added, or removed to match the search term.

  • Complex queries with AND, OR, parentheses, or multiple colons are not supported with fuzzy search

Table 4. Examples
Search Query Result Explanation

"henesy" with fuzzy=2

"honest" (first), "hennessy" (second)

"honest" has 2 character differences (e, h swapped, n added) without adding characters, which algorithm considers a better match than "hennessy" which has 2 character differences with 2 added characters.

"roam" with fuzzy=1

"roam", "foam", "roams"

Matches terms within 1 character difference: "roam" (exact match), "foam" (changed 'r' to 'f'), "roams" (added 's').

"cat" with fuzzy=1

"cat", "cut", "bat", "cats"

Matches terms within 1 edit distance: "cat" (exact match), "cut" (changed 'a' to 'u'), "bat" (changed 'c' to 'b'), "cats" (added 's').

Phonetic mismatch

"phonic" with fuzzy=2 does NOT match "fonic"

Fuzzy does not consider phonetics. "phonic" and "fonic" are phonetically similar but have different character patterns, so fuzzy does not match them.

4.2. Search Query

POST /api/v1/search/query/{collection}

4.2.1. Success

HTTP request
POST /api/v1/search/query/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "q1",
  "rangeFacets" : {
    "prices" : {
      "field" : "price",
      "gap" : 10,
      "start" : 0,
      "end" : 100
    }
  },
  "query" : "name:Lime",
  "start" : 0,
  "facetLimit" : 3,
  "text" : "Bud",
  "filters" : {
    "category_s" : "Beer"
  },
  "rows" : 2,
  "statFacets" : {
    "avgPrice" : "avg(price)"
  },
  "fuzzy" : 1,
  "return" : [ "id,sku,name,pack_size" ],
  "facets" : [ "sub_category_s", "brand_s", "type_s" ]
}
Response body
{
  "request" : {
    "facetLimit" : 3,
    "facets" : [ "sub_category_s", "brand_s", "type_s" ],
    "filters" : {
      "category_s" : "Beer"
    },
    "fuzzy" : 1,
    "nested" : false,
    "query" : "name:Lime",
    "quickSearch" : false,
    "rangeFacets" : {
      "prices" : {
        "end" : 100.0,
        "field" : "price",
        "gap" : 10.0,
        "start" : 0.0,
        "statFacets" : null
      }
    },
    "ref" : "q1",
    "return" : [ "id,sku,name,pack_size" ],
    "rows" : 2,
    "start" : 0,
    "statFacets" : {
      "avgPrice" : "avg(price)"
    },
    "text" : "Bud"
  },
  "resTime" : 48,
  "results" : {
    "response" : {
      "numFound" : 16,
      "start" : 0,
      "numFoundExact" : true,
      "docs" : [ {
        "id" : "57",
        "sku" : 1000000057,
        "pack_size" : 6,
        "name" : "Bud Light Lime-A-Rita Splash"
      }, {
        "id" : "51",
        "sku" : 1000000051,
        "pack_size" : 6,
        "name" : "Bud Light Lime Straw-Ber-Rita Splash"
      } ]
    },
    "facets" : {
      "count" : 16,
      "avgPrice" : 4.0625,
      "type_s" : {
        "buckets" : [ {
          "val" : "Coolers & Malt Beverages",
          "count" : 10
        }, {
          "val" : "Lager",
          "count" : 6
        } ]
      },
      "sub_category_s" : {
        "buckets" : [ {
          "val" : "Domestic Beer",
          "count" : 16
        } ]
      },
      "prices" : {
        "buckets" : [ {
          "val" : 0.0,
          "count" : 15
        }, {
          "val" : 10.0,
          "count" : 0
        }, {
          "val" : 20.0,
          "count" : 0
        }, {
          "val" : 30.0,
          "count" : 0
        }, {
          "val" : 40.0,
          "count" : 0
        }, {
          "val" : 50.0,
          "count" : 0
        }, {
          "val" : 60.0,
          "count" : 1
        }, {
          "val" : 70.0,
          "count" : 0
        }, {
          "val" : 80.0,
          "count" : 0
        }, {
          "val" : 90.0,
          "count" : 0
        } ]
      },
      "brand_s" : {
        "buckets" : [ {
          "val" : "Bud Light",
          "count" : 16
        } ]
      }
    }
  }
}

4.2.2. Quick Search

HTTP request
POST /api/v1/search/query/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "q1",
  "quickSearch" : "true",
  "text" : "Abita Andygator",
  "return" : [ "id,sku,name,pack_size" ]
}
Response body
{
  "request" : {
    "facetLimit" : 5,
    "fuzzy" : 0,
    "nested" : false,
    "quickSearch" : true,
    "ref" : "q1",
    "return" : [ "id,sku,name,pack_size" ],
    "rows" : 10,
    "start" : 0,
    "text" : "Abita Andygator"
  },
  "resTime" : 46,
  "results" : {
    "response" : {
      "numFound" : 1,
      "start" : 0,
      "numFoundExact" : true,
      "docs" : [ {
        "id" : "3",
        "sku" : 1000000003,
        "pack_size" : 6,
        "name" : "Abita Andygator"
      } ]
    }
  }
}

4.2.3. Highlighting

HTTP request
POST /api/v1/search/query/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "q1",
  "text" : "Bud",
  "highlighting" : [ "name", "short_desc" ],
  "return" : [ "id,sku,name,pack_size" ]
}
Response body
{
  "request" : {
    "facetLimit" : 5,
    "fuzzy" : 0,
    "highlighting" : [ "name", "short_desc" ],
    "nested" : false,
    "quickSearch" : false,
    "ref" : "q1",
    "return" : [ "id,sku,name,pack_size" ],
    "rows" : 10,
    "start" : 0,
    "text" : "Bud"
  },
  "resTime" : 50,
  "results" : {
    "response" : {
      "numFound" : 45,
      "start" : 0,
      "numFoundExact" : true,
      "docs" : [ {
        "id" : "68",
        "sku" : 1000000068,
        "pack_size" : 12,
        "name" : "Bud Light Platinum"
      }, {
        "id" : "69",
        "sku" : 1000000069,
        "pack_size" : 6,
        "name" : "Bud Light Platinum"
      }, {
        "id" : "70",
        "sku" : 1000000070,
        "pack_size" : 18,
        "name" : "Bud Light Platinum"
      }, {
        "id" : "71",
        "sku" : 1000000071,
        "pack_size" : 4,
        "name" : "Bud Light Platinum"
      }, {
        "id" : "72",
        "sku" : 1000000072,
        "pack_size" : 12,
        "name" : "Bud Light Platinum"
      }, {
        "id" : "73",
        "sku" : 1000000073,
        "name" : "Bud Light Platinum"
      }, {
        "id" : "36",
        "sku" : 1000000036,
        "name" : "Bud Light & Clamato Chelada"
      }, {
        "id" : "37",
        "sku" : 1000000037,
        "pack_size" : 12,
        "name" : "Bud Light Guav-A-Rita"
      }, {
        "id" : "48",
        "sku" : 1000000048,
        "pack_size" : 12,
        "name" : "Bud Light Lime Grape-A-Rita"
      }, {
        "id" : "24172",
        "sku" : 1000024164,
        "pack_size" : 12,
        "name" : "Bud Light Seltzer Cocktail Hour Variety Pack"
      } ]
    },
    "highlighting" : {
      "68" : {
        "name" : [ "<em>Bud</em> Light Platinum" ],
        "short_desc" : [ "<em>Bud</em> Light Platinum is an American-style Light Lager, a premium beer that takes classic <em>Bud</em> Light to the next level. " ]
      },
      "69" : {
        "name" : [ "<em>Bud</em> Light Platinum" ],
        "short_desc" : [ "<em>Bud</em> Light Platinum is an American-style Light Lager, a premium beer that takes classic <em>Bud</em> Light to the next level. " ]
      },
      "70" : {
        "name" : [ "<em>Bud</em> Light Platinum" ],
        "short_desc" : [ "<em>Bud</em> Light Platinum is an American-style Light Lager, a premium beer that takes classic <em>Bud</em> Light to the next level. " ]
      },
      "71" : {
        "name" : [ "<em>Bud</em> Light Platinum" ],
        "short_desc" : [ "<em>Bud</em> Light Platinum is an American-style Light Lager, a premium beer that takes classic <em>Bud</em> Light to the next level. " ]
      },
      "72" : {
        "name" : [ "<em>Bud</em> Light Platinum" ],
        "short_desc" : [ "<em>Bud</em> Light Platinum is an American-style Light Lager, a premium beer that takes classic <em>Bud</em> Light to the next level. " ]
      },
      "73" : {
        "name" : [ "<em>Bud</em> Light Platinum" ],
        "short_desc" : [ "<em>Bud</em> Light Platinum is an American-style Light Lager, a premium beer that takes classic <em>Bud</em> Light to the next level. " ]
      },
      "36" : {
        "name" : [ "<em>Bud</em> Light & Clamato Chelada" ],
        "short_desc" : [ "<em>Bud</em> Light & Clamato Chelada combines the refreshing taste of <em>Bud</em> Light with the richness of a Clamato tomato cocktail, spices and a hint of lime. " ]
      },
      "37" : {
        "name" : [ "<em>Bud</em> Light Guav-A-Rita" ]
      },
      "48" : {
        "name" : [ "<em>Bud</em> Light Lime Grape-A-Rita" ],
        "short_desc" : [ "Straight up more flavor with <em>Bud</em> Light Lime Grape-A-Rita! Juicy grape flavor combined with a classic margarita for Grape taste with a refreshing splash of <em>Bud</em> Light Lime. " ]
      },
      "24172" : {
        "name" : [ "<em>Bud</em> Light Seltzer Cocktail Hour Variety Pack" ]
      }
    }
  }
}

4.2.4. Nested Documents

HTTP request
POST /api/v1/search/query/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "s3",
  "start" : 0,
  "filters" : {
    "id" : "1 2 3 4 5"
  },
  "rows" : 5,
  "nested" : true,
  "fuzzy" : 0,
  "return" : [ ]
}
Response body
{
  "request" : {
    "facetLimit" : 5,
    "filters" : {
      "id" : "1 2 3 4 5"
    },
    "fuzzy" : 0,
    "nested" : true,
    "quickSearch" : false,
    "ref" : "s3",
    "return" : [ ],
    "rows" : 5,
    "start" : 0
  },
  "resTime" : 65,
  "results" : {
    "response" : {
      "numFound" : 1,
      "start" : 0,
      "numFoundExact" : true,
      "docs" : [ {
        "thumb_url" : "https://images.gotoliquorstore.com/product/1000000001/b030d7f1-0d21-4560-9996-a04c213b75f1_360.jpg",
        "package_size" : "25oz Can",
        "sub_category" : "Domestic Beer",
        "suggest" : [ "Domestic Beer", "Lager", "American-Style Lager", "1000000001", "10 Barrel", "10 Barrel Pub Beer", "Beer" ],
        "unit_size" : 25.0,
        "sub_brand" : "10 Barrel Pub Beer",
        "created_at" : "2019-05-22T14:19:23.000Z",
        "type" : "Lager",
        "unit_type" : "oz",
        "origin_state" : "Oregon",
        "updated_at" : "2025-10-29T10:02:24.000Z",
        "sub_type" : "American-Style Lager",
        "price" : 19.0,
        "sugar_free" : false,
        "company" : "Anheuser-Busch InBev",
        "id" : "1",
        "sku" : 1000000001,
        "brand" : "10 Barrel",
        "unit_package_type" : "Can",
        "product_size" : "Single",
        "product_guid" : "566bb985-7e99-e911-aa03-168fd05e5150",
        "origin_country" : "United States",
        "origin_city" : "Bend",
        "name" : "10 Barrel Pub Beer",
        "short_desc" : "Pours a clear golden color. Biscuity malt aromas with hints of lemon and floral hop spices. Flavors of malty sweetness balanced by lemony, floral hop bitterness. Ultimately easy drinking and refreshing.",
        "category" : "Beer",
        "alcohol_pct" : 5.0,
        "gluten_free" : false,
        "name_s" : "10 Barrel Pub Beer",
        "type_s" : "Lager",
        "_root_" : "1",
        "origin_state_s" : "Oregon",
        "brand_s" : "10 Barrel",
        "origin_city_s" : "Bend",
        "_version_" : 1856377887805931520,
        "category_s" : "Beer",
        "origin_country_s" : "United States",
        "sub_brand_s" : "10 Barrel Pub Beer",
        "sub_type_s" : "American-Style Lager",
        "sub_category_s" : "Domestic Beer",
        "company_s" : "Anheuser-Busch InBev",
        "product_data" : [ {
          "product_id" : 10,
          "quantity" : 2,
          "double_test" : 1.11,
          "id" : "1/product_data#0",
          "_root_" : "1",
          "_version_" : 1856377887805931520
        }, {
          "product_id" : 20,
          "quantity" : 2,
          "id" : "1/product_data#1",
          "_root_" : "1",
          "_version_" : 1856377887805931520
        } ],
        "store_data" : {
          "store_id" : 1,
          "store_count" : 100,
          "id" : "1/store_data#",
          "_root_" : "1",
          "_version_" : 1856377887805931520
        }
      } ]
    }
  }
}

4.2.5. Expire Token

HTTP request
POST /api/v1/search/query/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "q1",
  "rangeFacets" : {
    "prices" : {
      "field" : "price",
      "gap" : 10,
      "start" : 0,
      "end" : 100
    }
  },
  "query" : "name:Lime",
  "start" : 0,
  "facetLimit" : 3,
  "text" : "Bud",
  "filters" : {
    "category_s" : "Beer"
  },
  "rows" : 2,
  "statFacets" : {
    "avgPrice" : "avg(price)"
  },
  "fuzzy" : 1,
  "return" : [ "id,sku,name,pack_size" ],
  "facets" : [ "sub_category_s", "brand_s", "type_s" ]
}
Response body
{
  "timestamp" : 1770612635887,
  "status" : 401,
  "code" : 1003,
  "message" : "Access token has been expired - eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk",
  "args" : [ "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk" ]
}

4.3. Search Queries

POST /api/v1/search/queries/{collection}

4.3.1. Success

HTTP request
POST /api/v1/search/queries/lipi-search-test
Authorization: Bearer {Token}

[ {
  "ref" : "q1",
  "query" : "name: Lime",
  "start" : 0,
  "rows" : 3,
  "fuzzy" : 0,
  "return" : [ "id,sku,name" ],
  "facets" : [ "category_s" ]
}, {
  "ref" : "q2",
  "start" : 0,
  "text" : "bus",
  "rows" : 3,
  "fuzzy" : 1,
  "return" : [ "id,name" ]
}, {
  "ref" : "s3",
  "query" : "name:bus*",
  "start" : 0,
  "rows" : 3,
  "fuzzy" : 0,
  "return" : [ "id,name" ]
} ]
Response body
[ {
  "request" : {
    "facetLimit" : 5,
    "facets" : [ "category_s" ],
    "fuzzy" : 0,
    "nested" : false,
    "query" : "name: Lime",
    "quickSearch" : false,
    "ref" : "q1",
    "return" : [ "id,sku,name" ],
    "rows" : 3,
    "start" : 0
  },
  "resTime" : 45,
  "results" : {
    "response" : {
      "numFound" : 57,
      "start" : 0,
      "numFoundExact" : true,
      "docs" : [ {
        "id" : "42",
        "sku" : 1000000042,
        "name" : "Bud Light Lime"
      }, {
        "id" : "43",
        "sku" : 1000000043,
        "name" : "Bud Light Lime"
      }, {
        "id" : "44",
        "sku" : 1000000044,
        "name" : "Bud Light Lime"
      } ]
    },
    "facets" : {
      "count" : 57,
      "category_s" : {
        "buckets" : [ {
          "val" : "Beer",
          "count" : 29
        }, {
          "val" : "Spirits",
          "count" : 16
        }, {
          "val" : "Extras",
          "count" : 12
        } ]
      }
    }
  }
}, {
  "request" : {
    "facetLimit" : 5,
    "fuzzy" : 1,
    "nested" : false,
    "quickSearch" : false,
    "ref" : "q2",
    "return" : [ "id,name" ],
    "rows" : 3,
    "start" : 0,
    "text" : "bus"
  },
  "resTime" : 45,
  "results" : {
    "response" : {
      "numFound" : 98,
      "start" : 0,
      "numFoundExact" : true,
      "docs" : [ {
        "id" : "51",
        "name" : "Bud Light Lime Straw-Ber-Rita Splash"
      }, {
        "id" : "52",
        "name" : "Bud Light Lime Straw-Ber-Rita Splash"
      }, {
        "id" : "57",
        "name" : "Bud Light Lime-A-Rita Splash"
      } ]
    }
  }
}, {
  "request" : {
    "facetLimit" : 5,
    "fuzzy" : 0,
    "nested" : false,
    "query" : "name:bus*",
    "quickSearch" : false,
    "ref" : "s3",
    "return" : [ "id,name" ],
    "rows" : 3,
    "start" : 0
  },
  "resTime" : 45,
  "results" : {
    "response" : {
      "numFound" : 10,
      "start" : 0,
      "numFoundExact" : true,
      "docs" : [ {
        "id" : "93",
        "name" : "Busch"
      }, {
        "id" : "94",
        "name" : "Busch"
      }, {
        "id" : "95",
        "name" : "Busch"
      } ]
    }
  }
} ]

4.3.2. Expire Token

HTTP request
POST /api/v1/search/queries/lipi-search-test
Authorization: Bearer {Token}

[ {
  "ref" : "q1",
  "query" : "name: Lime",
  "start" : 0,
  "rows" : 3,
  "fuzzy" : 0,
  "return" : [ "id,sku,name" ],
  "facets" : [ "category_s" ]
}, {
  "ref" : "q2",
  "start" : 0,
  "text" : "bus",
  "rows" : 3,
  "fuzzy" : 1,
  "return" : [ "id,name" ]
}, {
  "ref" : "s3",
  "query" : "name:bus*",
  "start" : 0,
  "rows" : 3,
  "fuzzy" : 0,
  "return" : [ "id,name" ]
} ]
Response body
{
  "timestamp" : 1770612636094,
  "status" : 401,
  "code" : 1003,
  "message" : "Access token has been expired - eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk",
  "args" : [ "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk" ]
}

5. Group

Table 5. Params
Param Default Example Description

ref

N/A

"g1"

Reference id/key/string of request going back in response as is. It has nothing to do with search. It helps caller to track correctly.

text*

N/A

"Be"

Standard text search which applies to provided groups

groups*

N/A

["category_s","type_s"]

Groups to search text in

starts

false

true

Search text as starts with

contains

false

false

Search text as contains

limit

5

10

Number of records combined in return
Returning result is sorted by count within given groups.
In "groups", use "_s" postfix for field having single text value (not "list" value). It gives non-tokenised proper as-is full multi-words value in response.
Params mark with * is mandatory

5.1. Search Group

POST /api/v1/search/group/{collection}

5.1.1. Success

HTTP request
POST /api/v1/search/group/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "g1",
  "contains" : true,
  "limit" : 3,
  "groups" : [ "category_s", "sub_category_s", "type_s" ],
  "text" : "Be",
  "starts" : true
}
Response body
{
  "request" : {
    "contains" : true,
    "groups" : [ "category_s", "sub_category_s", "type_s" ],
    "limit" : 3,
    "ref" : "g1",
    "starts" : true,
    "text" : "Be"
  },
  "resTime" : 11,
  "results" : [ {
    "id" : 1,
    "group" : "category_s",
    "value" : "Beer",
    "count" : 200,
    "starts" : true,
    "contains" : false
  }, {
    "id" : 5,
    "group" : "sub_category_s",
    "value" : "Domestic Beer",
    "count" : 179,
    "starts" : false,
    "contains" : true
  }, {
    "id" : 31,
    "group" : "type_s",
    "value" : "Specialty Beer",
    "count" : 96,
    "starts" : false,
    "contains" : true
  } ]
}

5.1.2. Required

HTTP request
POST /api/v1/search/group/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "g101",
  "contains" : true,
  "limit" : 5,
  "starts" : true
}
Response body
{
  "timestamp" : 1770612635757,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Groups are mandatory", "Text is mandatory" ]
}

5.1.3. Expire Token

HTTP request
POST /api/v1/search/group/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "g1",
  "contains" : true,
  "limit" : 3,
  "groups" : [ "category_s", "sub_category_s", "type_s" ],
  "text" : "Be",
  "starts" : true
}
Response body
{
  "timestamp" : 1770612635784,
  "status" : 401,
  "code" : 1003,
  "message" : "Access token has been expired - eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk",
  "args" : [ "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk" ]
}

5.2. Search Groups

POST /api/v1/search/groups/{collection}

5.2.1. Success

HTTP request
POST /api/v1/search/groups/lipi-search-test
Authorization: Bearer {Token}

[ {
  "ref" : "g1",
  "contains" : false,
  "limit" : 2,
  "groups" : [ "category_s" ],
  "text" : "Be",
  "starts" : true
}, {
  "ref" : "g2",
  "contains" : true,
  "limit" : 2,
  "groups" : [ "type_s" ],
  "text" : "Be",
  "starts" : false
} ]
Response body
[ {
  "request" : {
    "contains" : false,
    "groups" : [ "category_s" ],
    "limit" : 2,
    "ref" : "g1",
    "starts" : true,
    "text" : "Be"
  },
  "resTime" : 2,
  "results" : [ {
    "id" : 1,
    "group" : "category_s",
    "value" : "Beer",
    "count" : 200,
    "starts" : true,
    "contains" : false
  } ]
}, {
  "request" : {
    "contains" : true,
    "groups" : [ "type_s" ],
    "limit" : 2,
    "ref" : "g2",
    "starts" : false,
    "text" : "Be"
  },
  "resTime" : 2,
  "results" : [ {
    "id" : 31,
    "group" : "type_s",
    "value" : "Specialty Beer",
    "count" : 96,
    "starts" : false,
    "contains" : true
  }, {
    "id" : 34,
    "group" : "type_s",
    "value" : "Coolers & Malt Beverages",
    "count" : 34,
    "starts" : false,
    "contains" : true
  } ]
} ]

5.2.2. Expire Token

HTTP request
POST /api/v1/search/groups/lipi-search-test
Authorization: Bearer {Token}

[ {
  "ref" : "g1",
  "contains" : false,
  "limit" : 2,
  "groups" : [ "category_s" ],
  "text" : "Be",
  "starts" : true
}, {
  "ref" : "g2",
  "contains" : true,
  "limit" : 2,
  "groups" : [ "type_s" ],
  "text" : "Be",
  "starts" : false
} ]
Response body
{
  "timestamp" : 1770612635737,
  "status" : 401,
  "code" : 1003,
  "message" : "Access token has been expired - eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk",
  "args" : [ "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk" ]
}

6. Suggest

Table 6. Params
Param Default Example Description

ref

N/A

"g1"

Reference id/key/string of request going back in response as is. It has nothing to do with search. It helps caller to track correctly.

text*

N/A

"Be"

Standard text search which applies to provided suggests

count

5

3

Number of suggestions in response

suggestTypes

"["ANALYZED"]"

" [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ]"

The suggestTypes field defines the types of suggestions to be applied, such as ANALYZED, FUZZY, INFIX, BLENDED and FREETEXT, depending on the specific search requirements.
Params mark with * is mandatory

6.1. Search Suggest

POST /api/v1/search/suggest/{collection}

6.1.1. Success

HTTP request
POST /api/v1/search/suggest/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "s1",
  "suggestTypes" : [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ],
  "count" : 3,
  "text" : "lemon"
}
Response body
{
  "request" : {
    "count" : 3,
    "ref" : "s1",
    "suggestTypes" : [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ],
    "text" : "lemon"
  },
  "resTime" : 52,
  "results" : {
    "analyzed" : [ "Lemon", "Lemon and Lime", "Lemon Juice" ],
    "blended" : [ "Lemon and Lime", "Lemon Juice", "Lemon" ],
    "freetext" : [ "lemon", "lemonade", "lemongrass" ],
    "fuzzy" : [ "Lemon", "Lemon and Lime", "Lemon Juice" ],
    "infix" : [ "Iced Tea and Lemonade", "Iced Tea and Lemonade", "Bud Light Lemon-Ade-Rita" ]
  }
}

6.1.2. Required

HTTP request
POST /api/v1/search/suggest/lipi-search-test
Authorization: Bearer {Token}

{ }
Response body
{
  "timestamp" : 1770612636501,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Text is mandatory" ]
}

6.1.3. Expire Token

HTTP request
POST /api/v1/search/suggest/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "s1",
  "suggestTypes" : [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ],
  "count" : 3,
  "text" : "lemon"
}
Response body
{
  "timestamp" : 1770612636491,
  "status" : 401,
  "code" : 1003,
  "message" : "Access token has been expired - eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk",
  "args" : [ "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk" ]
}

6.2. Search Suggests

POST /api/v1/search/suggests/{collection}

6.2.1. Success

HTTP request
POST /api/v1/search/suggests/lipi-search-test
Authorization: Bearer {Token}

[ {
  "ref" : "s1",
  "suggestTypes" : [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ],
  "count" : 3,
  "text" : "lemon"
}, {
  "ref" : "s2",
  "suggestTypes" : [ "ANALYZED", "FREETEXT" ],
  "count" : 3,
  "text" : "lemon"
} ]
Response body
[ {
  "request" : {
    "count" : 3,
    "ref" : "s1",
    "suggestTypes" : [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ],
    "text" : "lemon"
  },
  "resTime" : 66,
  "results" : {
    "analyzed" : [ "Lemon", "Lemon and Lime", "Lemon Juice" ],
    "blended" : [ "Lemon and Lime", "Lemon Juice", "Lemon" ],
    "freetext" : [ "lemon", "lemonade", "lemongrass" ],
    "fuzzy" : [ "Lemon", "Lemon and Lime", "Lemon Juice" ],
    "infix" : [ "Iced Tea and Lemonade", "Iced Tea and Lemonade", "Bud Light Lemon-Ade-Rita" ]
  }
}, {
  "request" : {
    "count" : 3,
    "ref" : "s2",
    "suggestTypes" : [ "ANALYZED", "FREETEXT" ],
    "text" : "lemon"
  },
  "resTime" : 62,
  "results" : {
    "analyzed" : [ "Lemon", "Lemon and Lime", "Lemon Juice" ],
    "freetext" : [ "lemon", "lemonade", "lemongrass" ]
  }
} ]

7. Spell

Table 7. Params
Param Default Example Description

ref

N/A

"g1"

Reference id/key/string of request going back in response as is. It has nothing to do with search. It helps caller to track correctly.

text*

N/A

"Be"

Standard text search which applies to provide correct spellings

count

5

2

Number of spells in response
Params mark with * is mandatory

7.1. Search Spell

POST /api/v1/search/spell/{collection}

7.1.1. Success

HTTP request
POST /api/v1/search/spell/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "q1",
  "count" : 2,
  "text" : "michaelob"
}
Response body
{
  "request" : {
    "count" : 2,
    "ref" : "q1",
    "text" : "michaelob"
  },
  "resTime" : 50,
  "results" : [ "michelob" ]
}

7.1.2. Required

HTTP request
POST /api/v1/search/spell/lipi-search-test
Authorization: Bearer {Token}

{ }
Response body
{
  "timestamp" : 1770612636187,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Text is mandatory" ]
}

7.1.3. Expire Token

HTTP request
POST /api/v1/search/spell/lipi-search-test
Authorization: Bearer {Token}

{
  "ref" : "s1",
  "suggestTypes" : [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ],
  "count" : 3,
  "text" : "lemon"
}
Response body
{
  "timestamp" : 1770612636272,
  "status" : 401,
  "code" : 1003,
  "message" : "Access token has been expired - eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk",
  "args" : [ "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk" ]
}

7.2. Search Spells

POST /api/v1/search/spells/{collection}

7.2.1. Success

HTTP request
POST /api/v1/search/spells/lipi-search-test
Authorization: Bearer {Token}

[ {
  "ref" : "q1",
  "count" : 2,
  "text" : "michaelob"
}, {
  "ref" : "q2",
  "count" : 2,
  "text" : "taqila"
} ]
Response body
[ {
  "request" : {
    "count" : 2,
    "ref" : "q1",
    "text" : "michaelob"
  },
  "resTime" : 49,
  "results" : [ "michelob" ]
}, {
  "request" : {
    "count" : 2,
    "ref" : "q2",
    "text" : "taqila"
  },
  "resTime" : 49,
  "results" : [ "tequila" ]
} ]

8. Combine

8.1. Search Combine

POST /api/v1/search/combine/{collection}

8.1.1. Success

HTTP request
POST /api/v1/search/combine/lipi-search-test
Authorization: Bearer {Token}

{
  "suggests" : [ {
    "ref" : "s1",
    "suggestTypes" : [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ],
    "text" : "lemon"
  }, {
    "ref" : "s2",
    "suggestTypes" : [ "ANALYZED", "FREETEXT" ],
    "text" : "lemon"
  } ],
  "groups" : [ {
    "ref" : "g1",
    "contains" : false,
    "limit" : 2,
    "groups" : [ "category_s" ],
    "text" : "Be",
    "starts" : true
  }, {
    "ref" : "g2",
    "contains" : true,
    "limit" : 2,
    "groups" : [ "type_s" ],
    "text" : "Be",
    "starts" : false
  } ],
  "spells" : [ {
    "ref" : "q1",
    "text" : "michaelob"
  }, {
    "ref" : "q2",
    "text" : "taqila"
  }, {
    "ref" : "q2",
    "text" : "smrnof"
  } ],
  "queries" : [ {
    "ref" : "q1",
    "start" : 0,
    "text" : "bus",
    "rows" : 3,
    "fuzzy" : 0,
    "return" : [ "id,sku,name" ],
    "facets" : [ "category_s" ]
  }, {
    "ref" : "q2",
    "start" : 0,
    "text" : "bus",
    "rows" : 3,
    "fuzzy" : 1,
    "return" : [ "id,name" ]
  }, {
    "ref" : "s3",
    "query" : "name:bus*",
    "start" : 0,
    "rows" : 3,
    "fuzzy" : 0,
    "return" : [ "id,name" ]
  }, {
    "ref" : "q4",
    "query" : "name:Lime",
    "start" : 0,
    "facetLimit" : 3,
    "text" : "Bud",
    "filters" : {
      "category_s" : "Beer"
    },
    "rows" : 2,
    "statFacets" : {
      "avgPrice" : "avg(price)"
    },
    "fuzzy" : 1,
    "return" : [ "id,sku,name,pack_size" ],
    "facets" : [ "sub_category_s", "brand_s", "type_s" ]
  } ]
}
Response body
{
  "groups" : [ {
    "request" : {
      "contains" : false,
      "groups" : [ "category_s" ],
      "limit" : 2,
      "ref" : "g1",
      "starts" : true,
      "text" : "Be"
    },
    "resTime" : 43,
    "results" : [ {
      "id" : 1,
      "group" : "category_s",
      "value" : "Beer",
      "count" : 200,
      "starts" : true,
      "contains" : false
    } ]
  }, {
    "request" : {
      "contains" : true,
      "groups" : [ "type_s" ],
      "limit" : 2,
      "ref" : "g2",
      "starts" : false,
      "text" : "Be"
    },
    "resTime" : 12,
    "results" : [ {
      "id" : 31,
      "group" : "type_s",
      "value" : "Specialty Beer",
      "count" : 96,
      "starts" : false,
      "contains" : true
    }, {
      "id" : 34,
      "group" : "type_s",
      "value" : "Coolers & Malt Beverages",
      "count" : 34,
      "starts" : false,
      "contains" : true
    } ]
  } ],
  "queries" : [ {
    "request" : {
      "facetLimit" : 5,
      "facets" : [ "category_s" ],
      "fuzzy" : 0,
      "nested" : false,
      "quickSearch" : false,
      "ref" : "q1",
      "return" : [ "id,sku,name" ],
      "rows" : 3,
      "start" : 0,
      "text" : "bus"
    },
    "resTime" : 49,
    "results" : {
      "response" : {
        "numFound" : 0,
        "start" : 0,
        "numFoundExact" : true,
        "docs" : [ ]
      },
      "facets" : {
        "count" : 0
      }
    }
  }, {
    "request" : {
      "facetLimit" : 5,
      "fuzzy" : 1,
      "nested" : false,
      "quickSearch" : false,
      "ref" : "q2",
      "return" : [ "id,name" ],
      "rows" : 3,
      "start" : 0,
      "text" : "bus"
    },
    "resTime" : 50,
    "results" : {
      "response" : {
        "numFound" : 98,
        "start" : 0,
        "numFoundExact" : true,
        "docs" : [ {
          "id" : "51",
          "name" : "Bud Light Lime Straw-Ber-Rita Splash"
        }, {
          "id" : "52",
          "name" : "Bud Light Lime Straw-Ber-Rita Splash"
        }, {
          "id" : "57",
          "name" : "Bud Light Lime-A-Rita Splash"
        } ]
      }
    }
  }, {
    "request" : {
      "facetLimit" : 5,
      "fuzzy" : 0,
      "nested" : false,
      "query" : "name:bus*",
      "quickSearch" : false,
      "ref" : "s3",
      "return" : [ "id,name" ],
      "rows" : 3,
      "start" : 0
    },
    "resTime" : 50,
    "results" : {
      "response" : {
        "numFound" : 10,
        "start" : 0,
        "numFoundExact" : true,
        "docs" : [ {
          "id" : "93",
          "name" : "Busch"
        }, {
          "id" : "94",
          "name" : "Busch"
        }, {
          "id" : "95",
          "name" : "Busch"
        } ]
      }
    }
  }, {
    "request" : {
      "facetLimit" : 3,
      "facets" : [ "sub_category_s", "brand_s", "type_s" ],
      "filters" : {
        "category_s" : "Beer"
      },
      "fuzzy" : 1,
      "nested" : false,
      "query" : "name:Lime",
      "quickSearch" : false,
      "ref" : "q4",
      "return" : [ "id,sku,name,pack_size" ],
      "rows" : 2,
      "start" : 0,
      "statFacets" : {
        "avgPrice" : "avg(price)"
      },
      "text" : "Bud"
    },
    "resTime" : 50,
    "results" : {
      "response" : {
        "numFound" : 16,
        "start" : 0,
        "numFoundExact" : true,
        "docs" : [ {
          "id" : "57",
          "sku" : 1000000057,
          "pack_size" : 6,
          "name" : "Bud Light Lime-A-Rita Splash"
        }, {
          "id" : "51",
          "sku" : 1000000051,
          "pack_size" : 6,
          "name" : "Bud Light Lime Straw-Ber-Rita Splash"
        } ]
      },
      "facets" : {
        "count" : 16,
        "avgPrice" : 4.0625,
        "type_s" : {
          "buckets" : [ {
            "val" : "Coolers & Malt Beverages",
            "count" : 10
          }, {
            "val" : "Lager",
            "count" : 6
          } ]
        },
        "sub_category_s" : {
          "buckets" : [ {
            "val" : "Domestic Beer",
            "count" : 16
          } ]
        },
        "brand_s" : {
          "buckets" : [ {
            "val" : "Bud Light",
            "count" : 16
          } ]
        }
      }
    }
  } ],
  "resTime" : 231,
  "spells" : [ {
    "request" : {
      "count" : 5,
      "ref" : "q1",
      "text" : "michaelob"
    },
    "resTime" : 51,
    "results" : [ "michelob" ]
  }, {
    "request" : {
      "count" : 5,
      "ref" : "q2",
      "text" : "taqila"
    },
    "resTime" : 50,
    "results" : [ "tequila" ]
  }, {
    "request" : {
      "count" : 5,
      "ref" : "q2",
      "text" : "smrnof"
    },
    "resTime" : 53,
    "results" : [ "smirnoff" ]
  } ],
  "suggests" : [ {
    "request" : {
      "count" : 5,
      "ref" : "s1",
      "suggestTypes" : [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ],
      "text" : "lemon"
    },
    "resTime" : 55,
    "results" : {
      "analyzed" : [ "Lemon", "Lemon and Lime", "Lemon Juice", "Lemon, Raspberry, Cherry and Berry" ],
      "blended" : [ "Lemon and Lime", "Lemon Juice", "Lemon", "Monaco Lemon Lime Vodka Soda", "Raspberry and Lemongrass" ],
      "freetext" : [ "lemon", "lemonade", "lemongrass" ],
      "fuzzy" : [ "Lemon", "Lemon and Lime", "Lemon Juice", "Lemon, Raspberry, Cherry and Berry" ],
      "infix" : [ "Iced Tea and Lemonade", "Iced Tea and Lemonade", "Bud Light Lemon-Ade-Rita", "Bud Light Lemon-Ade-Rita", "Lemon" ]
    }
  }, {
    "request" : {
      "count" : 5,
      "ref" : "s2",
      "suggestTypes" : [ "ANALYZED", "FREETEXT" ],
      "text" : "lemon"
    },
    "resTime" : 55,
    "results" : {
      "analyzed" : [ "Lemon", "Lemon and Lime", "Lemon Juice", "Lemon, Raspberry, Cherry and Berry" ],
      "freetext" : [ "lemon", "lemonade", "lemongrass" ]
    }
  } ]
}

8.1.2. Invalid

HTTP request
POST /api/v1/search/combine/lipi-search-test
Authorization: Bearer {Token}

{
  "groups" : [ {
    "ref" : "g101",
    "contains" : true,
    "limit" : 1,
    "starts" : true
  } ],
  "queries" : [ {
    "ref" : "q1",
    "start" : 0,
    "text" : "bus",
    "rows" : 3,
    "fuzzy" : 0,
    "return" : [ "id,sku,name" ],
    "facets" : [ "category_s" ]
  } ]
}
Response body
{
  "timestamp" : 1770612635649,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Groups are mandatory", "Text is mandatory" ]
}

8.1.3. Expire Token

HTTP request
POST /api/v1/search/combine/lipi-search-test
Authorization: Bearer {Token}

{
  "suggests" : [ {
    "ref" : "s1",
    "suggestTypes" : [ "ANALYZED", "FUZZY", "INFIX", "BLENDED", "FREETEXT" ],
    "text" : "lemon"
  }, {
    "ref" : "s2",
    "suggestTypes" : [ "ANALYZED", "FREETEXT" ],
    "text" : "lemon"
  } ],
  "groups" : [ {
    "ref" : "g1",
    "contains" : false,
    "limit" : 2,
    "groups" : [ "category_s" ],
    "text" : "Be",
    "starts" : true
  }, {
    "ref" : "g2",
    "contains" : true,
    "limit" : 2,
    "groups" : [ "type_s" ],
    "text" : "Be",
    "starts" : false
  } ],
  "spells" : [ {
    "ref" : "q1",
    "text" : "michaelob"
  }, {
    "ref" : "q2",
    "text" : "taqila"
  }, {
    "ref" : "q2",
    "text" : "smrnof"
  } ],
  "queries" : [ {
    "ref" : "q1",
    "start" : 0,
    "text" : "bus",
    "rows" : 3,
    "fuzzy" : 0,
    "return" : [ "id,sku,name" ],
    "facets" : [ "category_s" ]
  }, {
    "ref" : "q2",
    "start" : 0,
    "text" : "bus",
    "rows" : 3,
    "fuzzy" : 1,
    "return" : [ "id,name" ]
  }, {
    "ref" : "s3",
    "query" : "name:bus*",
    "start" : 0,
    "rows" : 3,
    "fuzzy" : 0,
    "return" : [ "id,name" ]
  }, {
    "ref" : "q4",
    "query" : "name:Lime",
    "start" : 0,
    "facetLimit" : 3,
    "text" : "Bud",
    "filters" : {
      "category_s" : "Beer"
    },
    "rows" : 2,
    "statFacets" : {
      "avgPrice" : "avg(price)"
    },
    "fuzzy" : 1,
    "return" : [ "id,sku,name,pack_size" ],
    "facets" : [ "sub_category_s", "brand_s", "type_s" ]
  } ]
}
Response body
{
  "timestamp" : 1770612635625,
  "status" : 401,
  "code" : 1003,
  "message" : "Access token has been expired - eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk",
  "args" : [ "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29kZSI6MCwiYWNjb3VudFR5cGUiOiJXaGl0ZSBMYWJlbCIsIm5hbWUiOiJTZWFyY2ggVXNlciIsImV4cCI6MTc1MTk4NDEyMH0.pXeKltDx5nSXMe4RqKjOFBAB2-CulSGuE8NgEkuNpjk" ]
}

APIs (Data)

9. Import (From Database)

Table 8. Data Types
Type Example Description

text

Giraffe on a Bicycle

Represents text data, typically used for database columns of type text or varchar. (Supports tokenized search.)

string

Orange

Represents string data, typically used for database columns of type text or varchar.

int

100

Represents integer values, used for database columns of type int (e.g., 100, 25).

long

12312363734

Represents long integer values, used for database columns of type long (e.g., 12312363734, 24312312734).

double

123.00

Represents floating-point values with decimals, used for database columns of type double (e.g., 123.00, 243.45).

boolean

true, false, 1, 0

Represents boolean values, typically used for database columns of type boolean (e.g., true, false, 1, 0).

date

2025-01-01T08:10:08

Represents date-time values, commonly used for database columns of type date (e.g., 2025-01-01 08:00:24.0).

jsonlist

["apple","orange"]

List of values in json format.

nested

{"store_id":2,"store_count":200}

Object in json format.

nestedlist

[{"product_id":2,"quantity":1,"price":10.99},{"product_id":179,"quantity":1,"price":5.99}]

List of Object in json format.
Considering "text" field’s tokenized characteristics; it can’t be used as "string" field for exact match in query for search or group creation for filters.

9.1. Import All

PUT /api/v1/data/import/all/{collection} (Asynchronous call)
Request
PUT /api/v1/data/import/all/{collection}
Content-Type: application/json
Authorization: Bearer {Data Token}
Response
true

9.2. Import Delta

PUT /api/v1/data/import/delta/{collection} (Asynchronous call)
Delta import column will be taken from data.json; specified in given colleciton as dataDeltaImportColumn. Delta import will be ignore if configuration is not being set or found.
Request
PUT /api/v1/data/import/delta/{collection}
Content-Type: application/json
Authorization: Bearer {Data Token}
Response
true

9.3. Import By Ids

PUT /api/v1/data/import/ids/{collection} (Asynchronous call)
Request
PUT /api/v1/data/import/ids/{collection}
Content-Type: application/json
Authorization: Bearer {Data Token}
`
[
    3,
    4
]
`
Response
true

9.4. Import By Id

PUT /api/v1/data/import/id/{collection}/{id} (Asynchronous call)
Request
PUT /api/v1/data/import/id/{collection}/{id}
Content-Type: application/json
Authorization: Bearer {Data Token}
Response
true

9.5. Import By Column

Import data by columns, like if records have been added in the last three days, update those records accordingly.
PUT /api/v1/data/import/column/{collection} (Asynchronous call)
Request
PUT /api/v1/data/import/column/{collection}
Content-Type: application/json
Authorization: Bearer {Data Token}
`
{
    "column": "updated_at",
    "from": "2025-02-17 11:46:35"
}
`
Response
true

10. Delete

10.1. Delete (All)

DELETE /api/v1/data/delete/all/{collection} (Asynchronous call)
Request
DELETE /api/v1/data/delete/all/{collection}
Content-Type: application/json
Authorization: Bearer {Data Token}
Response
true

10.2. Delete By Ids

DELETE /api/v1/data/delete/ids/{collection} (Asynchronous call)
Request
DELETE /api/v1/data/delete/ids/{collection}
Content-Type: application/json
Authorization: Bearer {Data Token}
`
[
    3,
    4
]
`
Response
true

10.3. Delete By Id

DELETE /api/v1/data/delete/id/{collection}/{id} (Asynchronous call)
Request
DELETE /api/v1/data/delete/id/{collection}/{id}
Content-Type: application/json
Authorization: Bearer {Data Token}
Response
true

11. Delete & Import

11.1. Delete & Import All

PUT /api/v1/data/delete/import/all/{collection} (Asynchronous call)
Request
PUT /api/v1/data/delete/import/all/{collection}
Content-Type: application/json
Authorization: Bearer {Data Token}
Response
true

12. Solr Group

LipiSearch manages cache for all groups for all the collections in memory for quick result.

LipiSearch refreshes groups whenever import process completes. However, for any special need of refreshing groups again, use following end points.

12.1. Refresh Solr Groups All

PUT /api/v1/data/solr/groups/refresh/all
Request
PUT /api/v1/data/solr/groups/refresh
Content-Type: application/json
Authorization: Bearer {Data Token}
Response
true

12.2. Refresh Solr Groups

PUT /api/v1/data/solr/groups/refresh/{collection}
Request
PUT /api/v1/data/solr/groups/refresh/{collection}
Content-Type: application/json
Authorization: Bearer {Data Token}
Response
true

APIs (Config)

13. Config

Gets the runtime configuration from the running instance.

Refer section Configuration to get a detailed understanding of various sections of the configuration file.

13.1. Read

POST /api/v1/config/read

13.1.1. Success

HTTP request
POST /api/v1/config/read
Authorization: Bearer {Token}

{
  "auth" : "auth-signature-test"
}
Response body
{
  "accountUrl" : "http://amd.techgrains.com:7777/lipiaccount",
  "collectionNames" : [ "lipi-search-test" ],
  "collections" : {
    "lipi-search-test" : {
      "collection" : "lipi-search-test",
      "data" : {
        "type" : "mysql",
        "url" : "jdbc:mysql://amd.techgrains.com:7706/lipisearchdb",
        "user" : "devlipisearchuser"
      },
      "dataDeltaImportColumn" : "updated_at",
      "dataImportPageSize" : 10000,
      "dataPrimaryColumn" : "id",
      "dataTable" : "lipi_search_test",
      "fullSearch" : [ ],
      "mappingFile" : "lipi-search-test.json",
      "mappings" : [ {
        "dataColumn" : "id",
        "dataType" : "int",
        "solrField" : "id",
        "solrType" : "string",
        "unique" : false
      }, {
        "dataColumn" : "sku",
        "dataType" : "int",
        "solrField" : "sku",
        "solrType" : "int",
        "unique" : false
      }, {
        "dataColumn" : "name",
        "dataType" : "text",
        "solrField" : "name",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "unit_package_type",
        "dataType" : "text",
        "solrField" : "unit_package_type",
        "solrType" : "string",
        "unique" : false
      }, {
        "dataColumn" : "package_size",
        "dataType" : "text",
        "solrField" : "package_size",
        "solrType" : "string",
        "unique" : false
      }, {
        "dataColumn" : "category",
        "dataType" : "text",
        "solrField" : "category",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "sub_category",
        "dataType" : "text",
        "solrField" : "sub_category",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "type",
        "dataType" : "text",
        "solrField" : "type",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "sub_type",
        "dataType" : "text",
        "solrField" : "sub_type",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "flavor",
        "dataType" : "text",
        "solrField" : "flavor",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "brand",
        "dataType" : "text",
        "solrField" : "brand",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "sub_brand",
        "dataType" : "text",
        "solrField" : "sub_brand",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "alcohol_pct",
        "dataType" : "double",
        "solrField" : "alcohol_pct",
        "solrType" : "double",
        "unique" : false
      }, {
        "dataColumn" : "origin_city",
        "dataType" : "text",
        "solrField" : "origin_city",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "origin_state",
        "dataType" : "text",
        "solrField" : "origin_state",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "origin_country",
        "dataType" : "text",
        "solrField" : "origin_country",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "company",
        "dataType" : "text",
        "solrField" : "company",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "short_desc",
        "dataType" : "text",
        "solrField" : "short_desc",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "pack_size",
        "dataType" : "int",
        "solrField" : "pack_size",
        "solrType" : "int",
        "unique" : false
      }, {
        "dataColumn" : "product_size",
        "dataType" : "text",
        "solrField" : "product_size",
        "solrType" : "string",
        "unique" : false
      }, {
        "dataColumn" : "unit_size",
        "dataType" : "double",
        "solrField" : "unit_size",
        "solrType" : "double",
        "unique" : false
      }, {
        "dataColumn" : "unit_type",
        "dataType" : "text",
        "solrField" : "unit_type",
        "solrType" : "string",
        "unique" : false
      }, {
        "dataColumn" : "region",
        "dataType" : "text",
        "solrField" : "region",
        "solrType" : "text",
        "unique" : false
      }, {
        "dataColumn" : "product_guid",
        "dataType" : "text",
        "solrField" : "product_guid",
        "solrType" : "string",
        "unique" : false
      }, {
        "dataColumn" : "gluten_free",
        "dataType" : "tinyint",
        "solrField" : "gluten_free",
        "solrType" : "boolean",
        "unique" : false
      }, {
        "dataColumn" : "sugar_free",
        "dataType" : "tinyint",
        "solrField" : "sugar_free",
        "solrType" : "boolean",
        "unique" : false
      }, {
        "dataColumn" : "thumb_url",
        "dataType" : "text",
        "solrField" : "thumb_url",
        "solrType" : "string",
        "unique" : false
      }, {
        "dataColumn" : "created_at",
        "dataType" : "datetime3",
        "solrField" : "created_at",
        "solrType" : "date",
        "unique" : false
      }, {
        "dataColumn" : "updated_at",
        "dataType" : "datetime2",
        "solrField" : "updated_at",
        "solrType" : "date",
        "unique" : false
      }, {
        "dataColumn" : "price",
        "dataType" : "double",
        "solrField" : "price",
        "solrType" : "double",
        "unique" : false
      }, {
        "dataColumn" : "product_data",
        "dataType" : "text",
        "solrField" : "product_data",
        "solrType" : "nestedlist",
        "unique" : false
      }, {
        "dataColumn" : "ProductId",
        "dataType" : "int",
        "solrField" : "product_id",
        "solrType" : "int",
        "unique" : false
      }, {
        "dataColumn" : "Quantity",
        "dataType" : "int",
        "solrField" : "quantity",
        "solrType" : "int",
        "unique" : false
      }, {
        "dataColumn" : "DoubleTest",
        "dataType" : "double",
        "solrField" : "double_test",
        "solrType" : "double",
        "unique" : false
      }, {
        "dataColumn" : "store_data",
        "dataType" : "text",
        "solrField" : "store_data",
        "solrType" : "nested",
        "unique" : false
      }, {
        "dataColumn" : "StoreId",
        "dataType" : "int",
        "solrField" : "store_id",
        "solrType" : "int",
        "unique" : false
      }, {
        "dataColumn" : "StoreCount",
        "dataType" : "int",
        "solrField" : "store_count",
        "solrType" : "int",
        "unique" : false
      } ],
      "quickSearch" : [ ],
      "solrGroups" : [ "category_s", "sub_category_s", "type_s", "sub_type_s", "flavor_s", "brand_s", "sub_brand_s" ],
      "stringify" : [ ],
      "suggestType" : [ ]
    }
  },
  "data" : [ {
    "type" : "mysql",
    "url" : "jdbc:mysql://amd.techgrains.com:7706/lipisearchdb",
    "user" : "devlipisearchuser"
  } ],
  "solr" : {
    "url" : "http://amd.techgrains.com:7783/solr",
    "user" : "solruser"
  }
}

13.1.2. Required

HTTP request
POST /api/v1/config/read
Authorization: Bearer {Token}

{ }
Response body
{
  "timestamp" : 1770612632311,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Auth is mandatory" ]
}

13.1.3. Invalid Auth

HTTP request
POST /api/v1/config/read
Authorization: Bearer {Token}

{
  "auth" : "auth-signature-invalid"
}
Response body
{
  "timestamp" : 1770612632326,
  "status" : 401,
  "code" : 1041,
  "message" : "Auth invalid - auth-signature-invalid",
  "args" : [ "auth-signature-invalid" ]
}

13.2. Collections

GET /api/v1/web/config/collections

13.2.1. Success

Request
GET /api/v1/web/config/collections
Content-Type: application/json
Authorization: Bearer {Token}

13.3. License

POST /api/v1/config/license

13.3.1. Success

HTTP request
POST /api/v1/config/license
Authorization: Bearer {Token}

{
  "auth" : "auth-signature-test"
}
Response body
{
  "aiEnable" : false,
  "auth" : "auth-signature-test",
  "collections" : 1,
  "daysLeft" : 325,
  "e" : "65537",
  "expireAt" : "2026-12-31",
  "expireAtDate" : "2026-12-31",
  "id" : 5,
  "invalid" : false,
  "key" : "hDVDyLmLRw179YATBf/WcEY9PcyTK/+v8gYtz1voJ92KpM2VlJ+oQlQsH9X+lRCZtLwLuwo61zNe4iL48nDn+CbqVwUozPndtRzXlO/5SyIRpIYXr7nJF76YaZbJGb1chnVsIn2bFtZ0vV5Th4HqXJTUxRNpVN0xLGKtTTO4Y2A=",
  "offline" : false,
  "owner" : "Techgrains Test",
  "records" : 1000,
  "rsa" : null,
  "secret" : "x9ap3ml7qwrt6zb2",
  "validationDisabled" : false,
  "version" : 1
}

13.3.2. Required

HTTP request
POST /api/v1/config/license
Authorization: Bearer {Token}

{ }
Response body
{
  "timestamp" : 1770612632251,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Auth is mandatory" ]
}

APIs (Admin)

Access
A token with a collection can access only that collection. A token without a collection can access all collections.
Uri Required

/api/v1/admin/…​

Admin Token

/api/v1/config/…​

Admin Token

/api/v1/data/…​

Data Token

/api/v1/search/…​

Search Token

14. Health

Various healths can be checked via following health check endpoints.

Table 9. Health Check
GET /health/{} Check For

Status

GET /health/status

Status of overall health

Ping

GET /health/ping

Data Search health

Solr

GET /health/solr

Apache Solr Index Server health

All

GET /health/all

Combined all health
All health check endpoints simply return true in healthy case and false otherwise.

14.1. Ping

Data Search health endpoint.

GET /health/ping

14.1.1. Success

HTTP request
GET /health/ping
Authorization: Bearer {Token}
Response body
{
  "ping" : true
}

14.2. Solr

Apache Solr Index Server health endpoint.

GET /health/solr

14.2.1. Success

HTTP request
GET /health/solr
Authorization: Bearer {Token}
Response body
{
  "solr" : true
}

14.3. Status

Status of overall health endpoint.

GET /health/status

14.3.1. Success

HTTP request
GET /health/status
Authorization: Bearer {Token}
Response body
{
  "all" : true,
  "ping" : true,
  "solr" : true,
  "solr-collections" : {
    "lipi-search-test" : true
  }
}

14.4. All

Combined all health endpoint.

GET /health/all

14.4.1. Success

HTTP request
GET /health/all
Authorization: Bearer {Token}
Response body
{
  "all" : true
}

15. Token

Roles are used to generate tokens that grant access to specific APIs, ensuring secure and role-based access control.
Table 10. Params
Role Description

ADMIN

Provides access to administrative APIs, such as Solr client refresh or update operations.

DATA

Allows access to data import and deletion APIs, such as Solr data import and deletion.

SEARCH

Enables access to search-related endpoints, including search, group and suggest functionalities.

15.1. Generate

POST /token/generate

15.1.1. Success

HTTP request
POST /api/v1/token/generate
Authorization: Bearer {Token}

{
  "code" : 121212,
  "role" : "SEARCH",
  "auth" : "auth-signature-test",
  "collections" : [ "lipi-search-test" ],
  "accountType" : "White Label",
  "name" : "Search User",
  "id" : 1,
  "validity" : 1
}
Response body
{
  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29sbGVjdGlvbnMiOlsibGlwaS1zZWFyY2gtdGVzdCJdLCJuYW1lIjoiU2VhcmNoIFVzZXIiLCJleHAiOjE3NzA2OTkwMzd9.elzibSBB-wscjxUPP8ywboyxv_gR96g2woFkIIt5_x8"
}

15.1.2. Required

HTTP request
POST /api/v1/token/generate
Authorization: Bearer {Token}

{
  "code" : 121212,
  "collections" : [ "lipi-search-test" ],
  "accountType" : "White Label"
}
Response body
{
  "timestamp" : 1770612637006,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Auth is mandatory", "Validity is mandatory", "Role is mandatory", "Id is mandatory", "Name is mandatory" ]
}

15.1.3. Auth Required

HTTP request
POST /api/v1/token/generate
Authorization: Bearer {Token}

{
  "code" : 121212,
  "role" : "SEARCH",
  "collections" : [ "lipi-search-test" ],
  "accountType" : "White Label",
  "name" : "Search User",
  "id" : 1,
  "validity" : 1
}
Response body
{
  "timestamp" : 1770612637017,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Auth is mandatory" ]
}

15.1.4. Invalid Auth

HTTP request
POST /api/v1/token/generate
Authorization: Bearer {Token}

{
  "code" : 121212,
  "role" : "SEARCH",
  "auth" : "auth-signature-invalid",
  "collections" : [ "lipi-search-test" ],
  "accountType" : "White Label",
  "name" : "Search User",
  "id" : 1,
  "validity" : 1
}
Response body
{
  "timestamp" : 1770612636981,
  "status" : 401,
  "code" : 1041,
  "message" : "Auth invalid - auth-signature-invalid",
  "args" : [ "auth-signature-invalid" ]
}

15.2. Decode

POST /token/decode

15.2.1. Success

HTTP request
POST /api/v1/token/decode
Authorization: Bearer {Token}

{
  "auth" : "auth-signature-test",
  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29sbGVjdGlvbnMiOlsibGlwaS1zZWFyY2gtdGVzdCJdLCJuYW1lIjoiU2VhcmNoIFVzZXIiLCJleHAiOjE3NzA2OTkwMzZ9.fE-9RSWKuvFVziP5O13g4BocGj2oyvLr7-gVKhbT5GU"
}
Response body
{
  "owner" : "Techgrains Test",
  "role" : "SEARCH",
  "collections" : [ "lipi-search-test" ],
  "name" : "Search User",
  "exp" : "2026-02-10T10:20:36"
}

15.2.2. Required

HTTP request
POST /api/v1/token/decode
Authorization: Bearer {Token}

{ }
Response body
{
  "timestamp" : 1770612636965,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Token is mandatory", "Auth is mandatory" ]
}

15.2.3. Auth Required

HTTP request
POST /api/v1/token/decode
Authorization: Bearer {Token}

{
  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29sbGVjdGlvbnMiOlsibGlwaS1zZWFyY2gtdGVzdCJdLCJuYW1lIjoiU2VhcmNoIFVzZXIiLCJleHAiOjE3NzA2OTkwMzZ9.fE-9RSWKuvFVziP5O13g4BocGj2oyvLr7-gVKhbT5GU"
}
Response body
{
  "timestamp" : 1770612636997,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "details" : [ "Auth is mandatory" ]
}

15.2.4. Invalid Auth

HTTP request
POST /api/v1/token/decode
Authorization: Bearer {Token}

{
  "auth" : "auth-signature-invalid",
  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUZWNoZ3JhaW5zIFRlc3QiLCJyb2xlIjoiU0VBUkNIIiwiY29sbGVjdGlvbnMiOlsibGlwaS1zZWFyY2gtdGVzdCJdLCJuYW1lIjoiU2VhcmNoIFVzZXIiLCJleHAiOjE3NzA2OTkwMzZ9.fE-9RSWKuvFVziP5O13g4BocGj2oyvLr7-gVKhbT5GU"
}
Response body
{
  "timestamp" : 1770612636808,
  "status" : 401,
  "code" : 1041,
  "message" : "Auth invalid - auth-signature-invalid",
  "args" : [ "auth-signature-invalid" ]
}

16. Solr

16.1. Update Client

Update specific solr client.

POST /api/v1/admin/update/client/{collection}

16.1.1. Success

HTTP request
POST /api/v1/admin/update/client/lipi-search-test
Authorization: Bearer {Token}

{ }
Response body
true

16.2. Update Clients

Update All solr clients.

POST /api/v1/admin/update/clients

16.2.1. Success

HTTP request
POST /api/v1/admin/update/clients
Authorization: Bearer {Token}

{ }
Response body
true

16.3. Schema Fields

To retrieve details of Solr fields, including both fields and copyFields.

POST /api/v1/admin/fields/{collection}

16.3.1. Success

HTTP request
GET /api/v1/admin/fields/lipi-search-test
Authorization: Bearer {Token}
Response body
{
  "fields" : {
    "_nest_path_" : [ "_nest_path_" ],
    "_root_" : [ "string", "indexed", "stored" ],
    "_text_" : [ "text_general", "indexed", "stored", "multiValued" ],
    "_version_" : [ "plong", "indexed", "stored" ],
    "alcohol_pct" : [ "pdouble" ],
    "brand" : [ "text_general" ],
    "brand_s" : [ "string", "indexed", "stored", "docValues" ],
    "category" : [ "text_general" ],
    "category_s" : [ "string", "indexed", "stored", "docValues" ],
    "company" : [ "text_general" ],
    "company_s" : [ "string", "indexed", "stored", "docValues" ],
    "created_at" : [ "pdate" ],
    "double_test" : [ "pdouble" ],
    "flavor" : [ "text_general" ],
    "flavor_s" : [ "string", "indexed", "stored", "docValues" ],
    "gluten_free" : [ "boolean" ],
    "id" : [ "string", "required", "multiValued" ],
    "keywords" : [ "text_general", "indexed", "stored", "multiValued" ],
    "name" : [ "text_general" ],
    "name_s" : [ "string", "indexed", "stored", "docValues" ],
    "origin_city" : [ "text_general" ],
    "origin_city_s" : [ "string", "indexed", "stored", "docValues" ],
    "origin_country" : [ "text_general" ],
    "origin_country_s" : [ "string", "indexed", "stored", "docValues" ],
    "origin_state" : [ "text_general" ],
    "origin_state_s" : [ "string", "indexed", "stored", "docValues" ],
    "pack_size" : [ "pint" ],
    "package_size" : [ "string" ],
    "price" : [ "pdouble" ],
    "product_data" : [ "text_general" ],
    "product_guid" : [ "string" ],
    "product_id" : [ "pint" ],
    "product_size" : [ "string" ],
    "quantity" : [ "pint" ],
    "quick_text" : [ "text_general", "indexed", "stored", "multiValued" ],
    "region" : [ "text_general" ],
    "region_s" : [ "string", "indexed", "stored", "docValues" ],
    "short_desc" : [ "text_general" ],
    "sku" : [ "pint" ],
    "store_count" : [ "pint" ],
    "store_data" : [ "text_general" ],
    "store_id" : [ "pint" ],
    "sub_brand" : [ "text_general" ],
    "sub_brand_s" : [ "string", "indexed", "stored", "docValues" ],
    "sub_category" : [ "text_general" ],
    "sub_category_s" : [ "string", "indexed", "stored", "docValues" ],
    "sub_type" : [ "text_general" ],
    "sub_type_s" : [ "string", "indexed", "stored", "docValues" ],
    "sugar_free" : [ "boolean" ],
    "suggest" : [ "text_suggest", "indexed", "stored", "multiValued" ],
    "text" : [ "text_general", "indexed", "stored", "multiValued" ],
    "thumb_url" : [ "string" ],
    "type" : [ "text_general" ],
    "type_s" : [ "string", "indexed", "stored", "docValues" ],
    "unit_package_type" : [ "string" ],
    "unit_size" : [ "pdouble" ],
    "unit_type" : [ "string" ],
    "updated_at" : [ "pdate" ]
  },
  "copyFields" : {
    "brand_s" : [ "brand" ],
    "category_s" : [ "category" ],
    "company_s" : [ "company" ],
    "flavor_s" : [ "flavor" ],
    "name_s" : [ "name" ],
    "origin_city_s" : [ "origin_city" ],
    "origin_country_s" : [ "origin_country" ],
    "origin_state_s" : [ "origin_state" ],
    "product_data_str" : [ "product_data" ],
    "quick_text" : [ "brand", "category", "name" ],
    "region_s" : [ "region" ],
    "store_data_str" : [ "store_data" ],
    "sub_brand_s" : [ "sub_brand" ],
    "sub_category_s" : [ "sub_category" ],
    "sub_type_s" : [ "sub_type" ],
    "suggest" : [ "brand", "category", "flavor", "name", "sku", "sub_category", "sub_type", "type" ],
    "text" : [ "brand", "category", "company", "flavor", "name", "short_desc", "sku", "sub_brand", "sub_category", "sub_type", "type", "unit_package_type" ],
    "type_s" : [ "type" ]
  }
}

17. Log

Plenty of logs can be possible in LipiSearch considering search and other activities/calls.

However, out of them the following types three activities (import, delete & token) are very crucial, which require to be logged and should be available through API for easier tracking or monitoring.

LipiSearch provides Log APIs for easier tracking and monitoring of the following types of logs.

Table 11. Log Types
Type For

IMPORT

Import data operations to collections

DELETE

Deletion operations upon data from collections

TOKEN

Token management
In-memory logging mechanism works only if LIPI_SEARCH_IN_MEMORY_LOG environment variable is set to true. By default, it will be considered as false.
System maintains these logs for a day in memory and clears it out every night @2:00am. (Or upon server restart.)

17.1. List

POST /api/v1/log/list
Non-specific collection logs won’t have collection entry. Don’t pass collection to fetch those logs.

17.1.1. All Filter

HTTP request
POST /api/v1/log/list?page=0&size=5
Authorization: Bearer {Token}

{
  "from" : "2026-02-08 10:20:34",
  "collection" : "lipi-search-test",
  "to" : "2026-02-10 10:20:34",
  "type" : "IMPORT",
  "status" : "INFO"
}
Response body
{
  "data" : [ {
    "collection" : "lipi-search-test",
    "message" : "Solr import started successfully",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import completed with warnings",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import started for batch 2",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import completed with no errors",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  } ],
  "totalCount" : 4
}

17.1.2. No Filter

HTTP request
POST /api/v1/log/list?page=0&size=5
Authorization: Bearer {Token}

{ }
Response body
{
  "data" : [ {
    "collection" : "lipi-search-test",
    "message" : "Solr import started successfully",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Token created",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "WARN",
    "type" : "TOKEN"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import failed due to timeout",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "ERROR",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import failed due to invalid data",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "ERROR",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import completed with warnings",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  } ],
  "totalCount" : 9
}

17.1.3. Stamp Filter

HTTP request
POST /api/v1/log/list?page=0&size=5
Authorization: Bearer {Token}

{
  "from" : "2026-02-08 10:20:34",
  "to" : "2026-02-10 10:20:34"
}
Response body
{
  "data" : [ {
    "collection" : "lipi-search-test",
    "message" : "Solr import started successfully",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Token created",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "WARN",
    "type" : "TOKEN"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import failed due to timeout",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "ERROR",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import failed due to invalid data",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "ERROR",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import completed with warnings",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  } ],
  "totalCount" : 9
}

17.1.4. Invalid Filter

HTTP request
POST /api/v1/log/list?page=0&size=5
Authorization: Bearer {Token}

{
  "to" : "2026-02-10 10:20:34"
}
Response body
{
  "timestamp" : 1770612634440,
  "status" : 400,
  "code" : 2052,
  "message" : "Invalid parameters",
  "args" : [ "from and to both should be null or present." ]
}

17.1.5. Collection Filter

HTTP request
POST /api/v1/log/list?page=0&size=5
Authorization: Bearer {Token}

{
  "collection" : "lipi-search-test"
}
Response body
{
  "data" : [ {
    "collection" : "lipi-search-test",
    "message" : "Solr import started successfully",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Token created",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "WARN",
    "type" : "TOKEN"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import failed due to timeout",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "ERROR",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import failed due to invalid data",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "ERROR",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import completed with warnings",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  } ],
  "totalCount" : 9
}

17.1.6. Type Filter

HTTP request
POST /api/v1/log/list?page=0&size=5
Authorization: Bearer {Token}

{
  "type" : "IMPORT"
}
Response body
{
  "data" : [ {
    "collection" : "lipi-search-test",
    "message" : "Solr import started successfully",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import failed due to timeout",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "ERROR",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import failed due to invalid data",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "ERROR",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import completed with warnings",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import started for batch 2",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  } ],
  "totalCount" : 8
}

17.1.7. Status Filter

HTTP request
POST /api/v1/log/list?page=0&size=5
Authorization: Bearer {Token}

{
  "status" : "INFO"
}
Response body
{
  "data" : [ {
    "collection" : "lipi-search-test",
    "message" : "Solr import started successfully",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import completed with warnings",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import started for batch 2",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  }, {
    "collection" : "lipi-search-test",
    "message" : "Solr import completed with no errors",
    "stamp" : "2026-02-09 10:20:34",
    "status" : "INFO",
    "type" : "IMPORT"
  } ],
  "totalCount" : 4
}

APIs (Chat)

18. Chat

Chat feature can be enabled through LIPI_SEARCH_AI_ENABLED as part of license.

18.1. Chat Message

POST /api/v1/chat
Request
POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer {Token}

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Hello, how are you?"
}
Response
{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "content": "I'm doing well, thank you for asking! How can I help you today?",
  "usage": {
    "model": "gpt-4",
    "promptTokens": 45,
    "completionTokens": 120,
    "totalTokens": 165,
    "timestamp": "2024-12-22T10:30:05.123Z"
  }
}

18.2. Chat Message (Collection)

POST /api/v1/chat/{collection}
Request
POST /api/v1/chat/lipi-search-test
Content-Type: application/json
Authorization: Bearer {Token}

{
  "conversationId": "0a00fff5-9636-427d-abc6-3e432f08f236",
  "message": "Search 3 products with text Barrel"
}
Response
{
  "conversationId": "0a00fff5-9636-427d-abc6-3e432f08f236",
  "content": "Here are three products related to the search term \"Barrel\":\n\n1. **10 Barrel Pub Beer**\n   - **Category:** Beer\n   - **Type:** Lager (American-Style Lager)\n   - **Size:** 25oz Can\n   - **Price:** $19.00\n   - **Description:** Pours a clear golden color. Biscuity malt aromas with hints of lemon and floral hop spices. Flavors of malty sweetness balanced by lemony, floral hop bitterness. Ultimately easy drinking and refreshing.\n   - **Brand:** 10 Barrel\n   - **Origin:** Bend, Oregon, United States\n\n2. **Woodford Reserve Aromatic Bitters**\n   - **Category:** Extras\n   - **Type:** Cocktail Bitters\n   - **Size:** 2oz Bottle\n   - **Price:** $0.00 (check for pricing as it might be an error)\n   - **Description:** Aromatic bitters made by Woodford Reserve, perfect for enhancing cocktails.\n   - **Brand:** Woodford Reserve\n   - **Origin:** Louisville, Kentucky, United States\n\n3. **Woodford Reserve Chocolate Bitters**\n   - **Category:** Extras\n   - **Type:** Cocktail Bitters\n   - **Size:** 2oz Bottle\n   - **Price:** $0.00 (check for pricing as it might be an error)\n   - **Description:** Chocolate-flavored bitters, ideal for adding complexity to mixed drinks.\n   - **Brand:** Woodford Reserve\n   - **Origin:** Louisville, Kentucky, United States",
  "usage": {
    "model": "gpt-4o-mini-2024-07-18",
    "promptTokens": 2082,
    "completionTokens": 530,
    "totalTokens": 2612,
    "timestamp": "2025-12-22T08:47:12.297918Z"
  }
}

18.3. Get Conversation

GET /api/v1/chat/get/{conversationId}
Request
GET /api/v1/chat/get/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
Authorization: Bearer {Token}
Response
[
  {
    "role": "user",
    "message": "Hello, how are you?",
    "stamp": "2024-12-22T10:30:00.000Z"
  },
  {
    "role": "assistant",
    "message": "I'm doing well, thank you for asking! How can I help you today?",
    "stamp": "2024-12-22T10:30:05.123Z"
  }
]

18.4. Reset Conversation

DELETE /api/v1/chat/reset/{conversationId}
Request
DELETE /api/v1/chat/reset/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
Authorization: Bearer {Token}
Response
true

APIs (Transcribe)

19. Transcribe

Transcribe feature can be enabled through LIPI_SEARCH_AI_ENABLED as part of license.

19.1. Audio

POST /api/v1/transcribe
Request
POST /api/v1/transcribe
Content-Type: application/json
Authorization: Bearer {Token}

Multipart: file=audio.mp3
Response
{
    "text": "I'm looking for Cabernet Sauvignon red wines from California."
}
POST /api/v1/transcribe?language=en&temperature=0.5
Supports Custom Params

  • language: Language of transcript text. i.e., en, es, fr etc.

  • temperature: Temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. By default it’s 0.

Request
POST /api/v1/transcribe?language=es&temperature=0.5
Content-Type: application/json
Authorization: Bearer {Token}

Multipart: file=audio.mp3
Response
{
    "text": "Estoy buscando Cabernet Sauvignon Red Wines de California.\n"
}

APIs (MCP)

20. MCP

MCP feature can be enabled through LIPI_SEARCH_AI_ENABLED as part of license.

20.1. MCP Info

GET /api/v1/mcp/info
Request
GET /api/v1/mcp/info
Content-Type: application/json
Authorization: Bearer {Token}
Response
{
  "serverInfo": {
    "name": "lipisearch-mcp-server",
    "version": "1.0.0"
  },
  "serverCapabilities": {
    "tools": true,
    "prompts": true,
    "resources": true
  },
  "clientInfo": {
    "name": "lipisearch-client",
    "version": "1.0.0"
  },
  "clientCapabilities": {
    "tools": true,
    "sampling": false
  },
  "toolsConfigured": 15
}

20.2. MCP Prompt

POST /api/v1/mcp/prompt/{name}
Request
POST /api/v1/mcp/prompt/greeting
Content-Type: application/json
Authorization: Bearer {Token}

{
  "name": "Amit Patel"
}
Response
{
  "description": "Greeting result",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "annotations": {
          "audience": [
            "user"
          ],
          "priority": 0.8
        },
        "text": "Namaste Amit Patel!"
      }
    }
  ]
}

20.3. MCP Resource

GET /api/v1/mcp/resource/{name}
Request
GET /api/v1/mcp/resource/version
Content-Type: application/json
Authorization: Bearer {Token}
Response
{
  "contents": [
    {
      "uri": "resource://version",
      "mimeType": "mime-type",
      "text": "1.0.0"
    }
  ]
}

20.4. MCP Tool

POST /api/v1/mcp/tool/{name}
Request
POST /api/v1/mcp/tool/search_products
Content-Type: application/json
Authorization: Bearer {Token}

{
  "collection": "lipi-search-test",
  "text": "Barrel",
  "limit": 2,
  "param1": "parameter 1"
}
Response
{
  "response": {
    "numFound": 12,
    "start": 0,
    "numFoundExact": true,
    "docs": [
      {
        "thumb_url": "https://images.gotoliquorstore.com/product/1000000001/b030d7f1-0d21-4560-9996-a04c213b75f1_360.jpg",
        "package_size": "25oz Can",
        "sub_category": "Domestic Beer",
        "suggest": [
          "Domestic Beer",
          "Lager",
          "American-Style Lager",
          "1000000001",
          "10 Barrel",
          "10 Barrel Pub Beer",
          "Beer"
        ],
        "unit_size": 25.0,
        "sub_brand": "10 Barrel Pub Beer",
        "created_at": 1558534763000,
        "type": "Lager",
        "unit_type": "oz",
        "origin_state": "Oregon",
        "updated_at": 1761732144000,
        "sub_type": "American-Style Lager",
        "price": 19.0,
        "sugar_free": false,
        "company": "Anheuser-Busch InBev",
        "id": "1",
        "sku": 1000000001,
        "brand": "10 Barrel",
        "unit_package_type": "Can",
        "product_size": "Single",
        "product_guid": "566bb985-7e99-e911-aa03-168fd05e5150",
        "origin_country": "United States",
        "origin_city": "Bend",
        "name": "10 Barrel Pub Beer",
        "short_desc": "Pours a clear golden color. Biscuity malt aromas with hints of lemon and floral hop spices. Flavors of malty sweetness balanced by lemony, floral hop bitterness. Ultimately easy drinking and refreshing.",
        "category": "Beer",
        "alcohol_pct": 5.0,
        "gluten_free": false
      },
      {
        "thumb_url": "https://images.gotoliquorstore.com/product/1000008835/8c195e9b-188c-43a4-b93f-539d8bc5b1f4_360.jpg",
        "unit_package_type": "Bottle",
        "package_size": "2oz Bottle",
        "sub_category": "Bitters",
        "suggest": [
          "Bitters",
          "Cocktail Bitters",
          "Woodford Reserve Aromatic Bitters",
          "1000008835",
          "Extras",
          "Woodford Reserve"
        ],
        "unit_size": 2.0,
        "product_size": "Single",
        "created_at": 1567152049000,
        "product_guid": "fc04b9f9-7ae3-4047-bc0c-b3fb6decb3ca",
        "type": "Cocktail Bitters",
        "unit_type": "oz",
        "origin_state": "Kentucky",
        "origin_country": "United States",
        "origin_city": "Louisville",
        "updated_at": 1731571294000,
        "price": 0.0,
        "name": "Woodford Reserve Aromatic Bitters",
        "sugar_free": false,
        "company": "Bourbon Barrel Foods, LLC",
        "id": "8841",
        "sku": 1000008835,
        "category": "Extras",
        "brand": "Woodford Reserve",
        "alcohol_pct": 44.0,
        "gluten_free": false
      }
    ]
  }
}

Technical

This section covers the technical aspects of configuring and customizing LipiSearch for your specific requirements. It includes environment setup, configuration management and integration details.

Most configurations are set up during initial deployment. Only modify these settings if you need to customize the default behavior or integrate with specific systems.
Architecture Overview

LipiSearch follows a microservices architecture with the following key components:

Component Description

Search Engine

Apache Solr cluster for indexing and search operations

API Gateway

RESTful API layer handling authentication and request routing

Configuration Manager

Manages system configuration, mappings and data sources

Data Import Service

Handles data ingestion from various sources (APIs, databases, files)
Configuration Types

LipiSearch uses several configuration files to define behavior:

  • Environment Configuration: Runtime settings and paths

  • License Configuration: License validation and feature access

  • Data Configuration: Data source definitions and collection mappings

  • Field Mappings: Custom field definitions and transformations

21. Configuration

All example values are for demonstration purposes only. Do not use example values in production environments without proper validation.

21.1. Environment

LipiSearch uses environment variables to configure runtime behavior. These variables can be set in your deployment environment or configuration files.

Variable Value Description

LIPI_SEARCH_CONFIG_DIR

/opt/lipisearch/config

Path to the main configuration directory containing solr.json, field mappings and other configuration files.

LIPI_SEARCH_LOGGING_LEVEL

INFO

Controls application logging verbosity. Options: DEBUG, INFO, WARN, ERROR. Use DEBUG for troubleshooting.

LIPI_SEARCH_IN_MEMORY_LOG

true or false

Enables in-memory logging for faster access to recent logs. Use true for development or debugging. (Default: false)

LIPI_SEARCH_AI_ENABLED

true or false

Enables or disables AI-powered features such as chat through MPC Tools. Set to true to activate LipiSearch AI capabilities. (Default: false)

LIPI_SEARCH_OPENAI_CHAT_MODEL

gpt-4o-mini

Specifies the OpenAI chat model to use for AI-powered features. Common options: gpt-4o-mini, gpt-4, gpt-3.5-turbo.

LIPI_SEARCH_OPENAI_AUDIO_MODEL

whisper-1

Specifies the OpenAI audio model for AI-powered speech to text. Common options: whisper-1, , gpt-4o-mini-transcribe, gpt-4o-transcribe.

LIPI_SEARCH_OPENAI_API_KEY

sk-proj-jAc5BjMizn5g…​

Your OpenAI API key for authenticating requests to OpenAI services. Required when LIPI_SEARCH_AI_ENABLED is set to true.

SOLR_JAVA_MEM

-Xms2048m -Xmx4096m

Configures Java memory allocation for Solr & LipiSearch. -Xms sets initial heap size, -Xmx sets maximum heap size. Adjust based on your data volume and available system resources.

LIPI_SEARCH_JAVA_MEM

-Xms2048m -Xmx4096m

21.2. Config Directory

LipiSearch API requires externally provided configurations as environment variable LIPI_SEARCH_CONFIG_DIR.

All the configuration-related information is part of the config directory; having various config files like data, license, security, solr & tool.

Here is a very high-level structure for the config directory.

config directory
Figure 1. Config Directory
Mappings

Defines field mappings and transformations between search index schema and source data.

Panels

Contains simulator-styled panel configurations for monitoring and api calling.

Data

Contains data-related configurations including data source connections, fields mapping file and full/delta import.

License

Stores license information and related configurations required for LipiSearch to operate.

Security

Defines Solr security configurations such as authentication and authorization rules, and access control policies.

Solr

Contains Apache Solr server instance and credentials to connect.

Tool

Includes MCP tool configurations to use for each collection and use AI prompt through a chat message via API.

Refer Config Read to get runtime configuration from the running instance.

22. Codes

Two types of codes are floating during entire API handshake.

  1. HTTP Codes

  2. Error Codes

HTTP Codes and Error Codes are defined accurately to pinpoint the exact problem with unique codes value.

HTTP codes are standard 3 digits. Error codes are of 4 digits.

22.1. Http Codes

API adheres to standard HTTP and REST conventions in its use of HTTP verbs and HTTP codes as closely as possible.

Table 12. HTTP Verbs
Verb Usage

[GET]

Used to retrieve a resource

[POST]

Used to create a new resource

[PUT]

Used to update an existing resource with full updates

[PATCH]

Used to update an existing resource with partial updates

[DELETE]

Used to delete an existing resource
Table 13. HTTP Codes
Status Code Abbreviation Error Codes Usage

200

OK

Standard response for successful HTTP requests.

401

UNAUTHORIZED

1xxx

The request is missing the auth or access in order to fulfill the request.

400

BAD_REQUEST

2xxx

The request is malformed, bad, invalid or having constraints.

404

NOT_FOUND

3xxx

The requested resource does not exist.

409

CONFLICT

8xxx

The request could not be completed due to a conflict with the current state of the target resource.

500

INTERNAL_SERVER_ERROR

9xxx

A generic error given when an unexpected condition was encountered.

22.2. Error Codes

API is based on complete token-based asynchronous mechanism which is extremely lightweight & fast.

Table 14. Error Codes
Code Key Description

1001

ACCESS_TOKEN_MISSING

Access token is missing

1002

ACCESS_TOKEN_INVALID

Access token is invalid

1003

ACCESS_TOKEN_EXPIRED

Access token has been expired - {0}

1004

ACCESS_TOKEN_NOT_CREATED

Access token not created - {0}

1031

LICENSE_KEY_INVALID

License key invalid - {0}

1032

LICENSE_AUTH_INVALID

License auth invalid - {0}

1033

LICENSE_EXPIRED

License is expired - {0}

1041

AUTH_INVALID

Auth invalid - {0}

1101

UNAUTHORIZED_ACCESS

Unauthorized access

1102

UNAUTHORIZED_COLLECTION_ACCESS

Unauthorized collection access

2001

REQUIRED_PARAM

Required {0} parameter {1} is missing

2051

INVALID_ENTITY

Invalid entity {0}

2052

INVALID_PARAMS

Invalid parameters

2053

INVALID_VALUE

Invalid value {0}

2054

INVALID_INSTANCE

Invalid instance {0}

2055

INVALID_ACCOUNT

Invalid account

2056

INVALID_MAPPINGS

Invalid Mappings for collection

2101

ALREADY_EXIST_ENTITY

Entity {0} with value {1} already exists

2221

SOLR_RECORDS_RANGE_EXCEED

Solr records range exceeded

2222

SOLR_COLLECTIONS_RANGE_EXCEED

Solr collections range exceeded

2301

CONSTRAINT_VIOLATION

Constraint violation

2401

UNABLE_TO_PARSE

Unable to parse {0} exception {1}

3001

NOT_FOUND_ENTITY

Entity {0} not found for {1}

9001

EXCEPTION

Generic exception

9002

NULL_POINTER_EXCEPTION

Null pointer exception

9003

SQL_EXCEPTION

SQL exception

9004

AI_EXCEPTION

Ai exception

9005

CUSTOM_EXCEPTION

Custom exception

9006

SOLR_CLIENT_EXCEPTION

Solr client exception

9007

HTTP_CLIENT_EXCEPTION

HttpClient exception

9008

LIPI_ACCOUNT_CLIENT_EXCEPTION

LipiAccountClient exception

9009

CONFIG_EXCEPTION

Config exception

23. Versions

LipiSearch has evolved through multiple versions, each introducing new capabilities & improvements.

All supported versions of LipiSearch are available through Docker Hub.
Docker Pull
$ docker pull techgrains/lipisearch:3.2

23.1. Version 3.2

Table 15. Components

Java Runtime

Eclipse Temurin 25 JRE

Spring Boot

4.0.2

Apache Solr

9.10.1 (Slim)
Updates

  • Improved container efficiency by switching to lightweight base images.

  • Enhanced search capabilities with boosted field support.

23.2. Version 3.1

Table 16. Components

Java Runtime

Eclipse Temurin 25

Spring Boot

4.0.1

Apache Solr

9.10.0
Updates

  • Unified LipiSearch as a singular all-in-one solution with all the features.

  • Introduces AI-powered Chat API and MCP tool configurations for advanced search capabilities.

24. Best Practices

24.1. Performance

Request Optimization

  • Use pagination: Limit results with start and rows parameters

  • Combine operations: Use the combine API for multiple searches

  • Cache responses: Implement client-side caching for frequently accessed data

  • Optimize queries: Use specific field searches instead of broad text searches when possible

Response Handling

  • Implement timeouts: Set appropriate timeout values for API calls

  • Handle errors gracefully: Always check response status and handle errors

  • Use async operations: For large data imports, use asynchronous processing

24.2. Security

Token Management

  • Rotate tokens regularly: Implement token rotation for enhanced security

  • Use appropriate roles: Assign minimal required permissions to tokens

  • Secure storage: Store tokens securely and never expose them in client-side code

  • Monitor usage: Track API usage and watch for unusual patterns

Data Protection

  • Validate input: Always validate and sanitize input data

  • Use HTTPS: Ensure all API communications use HTTPS

  • Implement CORS: Configure CORS properly for web applications

24.3. Integration

Search Implementation

  • Progressive enhancement: Start with basic search, add advanced features gradually

  • User feedback: Provide loading states and error messages

  • Fallback strategies: Implement fallbacks for when search is unavailable

Data Synchronization

  • Incremental updates: Use delta imports for large datasets

  • Batch operations: Group related operations for better performance

  • Error recovery: Implement retry logic for failed operations

24.4. Monitoring

Logging

  • Enable debug logging: Use DEBUG level for troubleshooting

  • Monitor performance: Track response times and error rates

  • Log requests: Keep request logs for debugging and analysis

Health Checks

  • Regular monitoring: Use health check endpoints to monitor service status

  • Alert systems: Set up alerts for service degradation

  • Performance metrics: Track key performance indicators

24.5. Code Examples

24.5.1. JavaScript/Node.js

const searchProducts = async (query, filters = {}) => {
  try {
    const response = await fetch('/api/v1/search/query/products', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${Token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text: query,
        filters: filters,
        start: 0,
        rows: 20
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const data = await response.json();
    return data.data;
  } catch (error) {
    console.error('Search error:', error);
    throw error;
  }
};

24.5.2. Python

import requests
import json

def search_products(query, filters=None):
    url = "https://your-domain.com/api/v1/search/query/products"
    headers = {
        "Authorization": f"Bearer {Token}",
        "Content-Type": "application/json"
    }

    payload = {
        "text": query,
        "filters": filters or {},
        "start": 0,
        "rows": 20
    }

    try:
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
        return response.json()["data"]
    except requests.exceptions.RequestException as e:
        print(f"Search error: {e}")
        raise

© 2025 Techgrains Technologies