API Documentation

Whether you’re looking to use our API for your own, custom-built website or you’re a professional helping another business make the most out of existing plugins, Zevi’s API has everything you need. Our versatile API solution enables easy, fast, and seamless integration while also allowing you to keep developing on top of it, without bloated code or limitations standing in your way.

Authentication:

In order to authenticate your request you must include two below mentioned parameters in the headers with every request you send to Zevi enapoints.

Include the API Key and Organization ID in the following header with every API request:

x-zevi-org-id: Organzation ID
x-zevi-api-key: API Key

curl -L -X POST 'https://api.zevi.ai/2023-01/stores'
-H "x-zevi-org-id: 63b5a4f23d36jvh3opc1th3dw" \
-H 'x-zevi-api-key: 9a940c8f-4609-4fa8-acab-5f4d55facfea'

This is how your request with headers would appear.

Products:

Customers can manage their products catalogs by using the below API's provided by Zevi. Details for the each of the enpoint which you can ustilize to manage your products catalogs are as below.

1. Create Products

All product ids must be unique and new. If any of the product ids match with the currently saved products, no products will be inserted and the request will be rejected.

Endpoint: POST https://api.zevi.ai/2023-01/products

Limit: 250 products/request

Example request:

curl -L -X POST 'https://api.zevi.ai/2023-01/products' \
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json' \
--data-raw '{
    "products": [{
        "product_id": "148576483920",
        "title": "Chocolate"
    }]
}'

Example Response:

status code: 200 for success

{
  "message": "Products added successfully"
}

Param	Type	Description
`products`	Array of product objects (required)	This is a required parameter of type array, which contains product objects with the following attributes: `product_id` (required, type string and must be unique per store), and `[any]` (type string, boolean, or number).

2. Get Products

Endpoint: GET https://api.zevi.ai/2023-01/products

Example request:

curl -L -X GET 'https://api.zevi.ai/2023-01/products' \
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json' \
--data-raw '{
        "per_page": 25,
        "page": 1,
        "product_ids": "129837,546372"
}'

Example Response:

status code: 200 for success

{
  "products": [
    {
      "product_id": "129837",
      "title": "Chocolate",
      "createdAt": "2023-01-09T19:43:25.014Z",
      "updatedAt": "2023-01-09T20:49:24.350Z"
    },
    {
      "product_id": "546372",
      "title": "Candy",
      "createdAt": "2023-01-09T19:43:28.059Z",
      "updatedAt": "2023-01-09T19:43:28.059Z"
    }
  ]
}

Param	Type	Description
`per_page`	Number (Default: 25, Max: 250)	This parameter is optional and specifies the number of items to return per page, with a maximum of 250 items. If not specified, the default value is 25.
`page`	Number (Default: 1)	This parameter is optional and specifies the page number to return. If not specified, the default value is 1.
`product_ids`	String (comma-separated values)	This parameter is optional and specifies a comma-separated list of product IDs to retrieve.

3. Update Products

All product ids must be present. The request will not update any product if any of the product ids are not currently present. If all the products are present then products will be updated.

Endpoint: PATCH https://api.zevi.ai/2023-01/products

Example request:

curl -L -X PATCH 'https://api.zevi.ai/2023-01/products' \
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json' \
--data-raw '{
    "products": [{
        "product_id": "129837",
        "title": "Chocolate"
    }]
}'

Example Response:

status code: 200 for success

{
  "message": "Products updated successfully"
}

Param	Type	Description
`products`	Array of product objects	This parameter is an array of product objects with the following supported attributes: `product_id` (required, type string and must be unique per store), and `[any]` (type string, boolean, or number).

4. Upsert Products

If a product is present then it will be updated. If a product does not exist, it will be created.

Endpoint: PUT https://api.zevi.ai/2023-01/products

Example request:

curl -L -X PUT 'https://api.zevi.ai/2023-01/products' \
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json' \
--data-raw '{
    "products": [{
        "product_id": "129837",
        "title": "Chocolate"
    }]
}'

Example Response:

status code: 200 for success

{
  "message": "Products created/updated successfully"
}

Param	Type	Description
`products`	Array of product objects	This parameter is an array of product objects with the following supported attributes: `product_id` (required, type string and must be unique per store), and `[any]` (type string, boolean, or number).

5. Delete Products

Endpoint: DELETE https://api.zevi.ai/2023-01/products

Example request:

curl -L -X DELETE 'https://api.zevi.ai/2023-01/products' \
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json' \
--data-raw '{
    "products": [{
        "product_id": "148576483920",
    }]
}'

Example Response:

status code: 200 for success

{
  "message": "products deleted successfully"
}

Param	Type	Description
`products`	Array of product objects	This parameter is an array of product objects with the following supported attribute: `product_id` (required, type string and must be unique per store).

Autocomplete

What is Autocomplete?

Autocomplete is a feature in search engines and other software applications that provides suggestions for search queries or phrases as the user types in the search bar. It predicts and suggests the most probable queries based on the search history, previous searches, and current location. Autocomplete offers suggestions to save time for the user, and it can also help users avoid spelling errors and typos.

The suggestions are usually presented as a dropdown list that appears beneath the search box, and users can select one of the suggestions by clicking on it or pressing the "enter" key. Autocomplete suggestions can be based on the most popular or recent searches, as well as on the user's past search history, location, and other relevant factors. The feature can be helpful in guiding users to find relevant information more quickly and accurately.

How can I use it?

At the below-mentioned endpoint, the Autocomplete feature offered by Zevi can be utilized

Endpoint: GET https://api.zevi.ai/2023-01/autocomplete

Sample request

curl --request GET 'https://api.zevi.ai/2023-01/autocomplete?store=63b5a4f23d3d68e12be783d9&q=ha'
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json'

Param	Type	Description
`store`	String	Store name or Org Id (Required)
`q`	String	Any search string which user enters (Required)

Sample response

{"autocomplete_list": [
                "walnut trees",
                "walnut brook",
                "walnut soap",
                "walnut wood flower pot",
                "walnut wood pen holder",
                "walnut wood book stand",
                "walnut wooden ledge",
                "walnut wood chinar stand",
                "walnut wood chinar tray",
                "walnut wood flower vase"
                ]
}

Search

An AI-driven NLP search, lets users search in the way that comes most naturally to them - and this is just the beginning. Our goal is to challenge the status quo in a space that hasn’t changed for decades, and transition context-powered search from a ‘good-to-have’ to an absolute essential for any growth-focused brand.

Below is the explaination and examples of usage for search offered by Zevi.AI

Endpoint: GET https://api.zevi.ai/2023-01/search

Sample request

curl --request GET 'https://api.zevi.ai/2023-01/search?limit=25&store=63b5a4f23d3d68e12be783d9&q=ha' 
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json'

Param	Type	Description
`store`	String	Store name or Org ID (Required)
`q`	String	Any search string which user enters (Required)
`pageno`	Positive Integer	Page number specified for the list of curated results (Default Value: 1)
`limit`	String	Number of results per page for a particular query (Default Value: 25)
`filter`	String	Results will be filtered based on the given criteria (filter={column_name}={column_value})

Sample response

{
  "ranked_list": [
    {
      "product_id": "74286",
      "title": "Beverage Cup",
      "description": "The glass-blown cup is the ideal companion for a cup of coffee or tea with the favorite homies. The tea is kept warm by the double-walled design, which makes the cup very comfortable to handle. Present tea in style with the beautiful, clear glass tea glasses, which are simple yet edgy. The glass cup is made of excellent quality material and is suitable for both formal as well as informal occasions. Set up the table with an elegant charm during an",
      "category1": "Home",
      "category2": "kitchenware & dining",
      "subcategory": "cup",
      "handle": "beverage-cup",
      "store_id": 227,
      "store_name": "Nestasia"
    },
    {
      "product_id": "74263",
      "title": "Milk Cup",
      "description": "Ceramic coffee cups in black are manufactured without any chemical processing and keeping in mind a need to carve a path for sustainable living. The elegant design and textured surface of the reusable coffee cup will compliment any table and home décor. Suit the needs of one's coffee table and be ready to be able to easily pair up the mugs with any snack plates of one's choice. The smooth matte finish of the mug prevents discoloration from takin",
      "category1": "Home",
      "category2": "kitchenware & dining",
      "subcategory": "cup",
      "handle": "milk-cup",
      "store_id": 227,
      "store_name": "Nestasia"
    },
    ...,
        ...
  ],
  "total_result_count": 10,
  "filters":[
      {
         "title":"Filter Color",
         "column_name":"filter_color",
         "type":"checkbox",
         "values":[
            "Blue",
            "Green",
            "Purple",
            "Black",
            "Red",
            "Orange",
            "Yellow",
            "Grey"
         ]
      },
      {
         "title":"Filter Price",
         "column_name":"filter_price",
         "type":"checkbox",
         "values":[
            "501-1000",
            "0-500",
            "1001-1500",
            "1501-2000",
            "2001-4000"
         ]
      },
      {
         "title":"Filter Size",
         "column_name":"filter_size",
         "type":"checkbox",
         "values":[
            "S",
            "M",
            "L",
            "XL",
            "XXL"
         ]
      },
      ...
  ]
}

Filters

What are filters?

Product filters are a common feature in ecommerce websites that allow users to narrow down their search for products based on specific criteria. These filters typically appear on category or search result pages, and allow users to refine their search results based on attributes such as price, brand, color, size, style, material, rating, and availability.

Product filters make it easier for users to find the products they are looking for, and can help increase sales and customer satisfaction by providing a more streamlined and personalized shopping experience. By using filters, users can quickly eliminate products that don't meet their specific needs, and focus on the ones that do.

In addition to improving the user experience, product filters can also provide valuable insights into customer behavior and preferences. Ecommerce businesses can use this information to optimize their product offerings and marketing strategies, and to better understand the needs and wants of their target audience.

Customize fitlers

For each search request, we offer a filter JSON array in our response, similar to the sample response shown above. This array includes various columns specific to the products and stores in question. To create, modify, or delete filters, you can use the Filter tab Dashaboard. It is possible to customize filters similar to the ones illustrated in the image above.

Assuming that you have already created the filters, you may want to refine your search results by using the color=Black filter. The following example of a search request will implement this filter and retrieve only the products that match the search query, and then further narrow down the search results to only include products with the color Black.

Sample request with filter

Filter parameter format: `filter={filter_column}={value}`

curl --request GET 'https://api.zevi.ai/2023-01/search?limit=25&store=63b5a4f23d3d68e12be783d9&q=ha&filter=filter_color=Black' 
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json'

As filter format mentioned above, you may notice that there is an additional parameter filter=filter_color=Black added to the search request. This parameter enables you to apply any other filter that you have previously created using the following format: filter={filter_column}={value}. You can apply all available filters in a single request, if desired.

Sample request with multiple filters on multiple columns

Filter parameter format: `filter={filter_column1}={value1}&filter={filter_column2}={value2}`

curl --request GET 'https://api.zevi.ai/2023-01/search?limit=25&store=63b5a4f23d3d68e12be783d9&q=ha&filter=filter_color=Black&filter=filter_size=XL' 
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json'

In this above sample request there are 2 filters applied on two different columns, One one color as filter=filter_color=Black and other is on size as filter=filter_size=XL

Sample request with multiple filters on same columns

Filter parameter format: `filter={filter_column1}={value1}&filter={filter_column1}={value2}`

curl --request GET 'https://api.zevi.ai/2023-01/search?limit=25&store=63b5a4f23d3d68e12be783d9&q=ha&filter=filter_color=Black&filter=filter_color=Green' 
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json'

In this above sample request there are 2 filters applied on same columns, One one color as filter=filter_color=Black and other is on size as filter=filter_color=Green

Sample request with range based filters

Filter parameter format: `filter={filter_column}={min_value}-{max_value}`

curl --request GET 'https://api.zevi.ai/2023-01/search?limit=25&store=63b5a4f23d3d68e12be783d9&q=ha&filter=filter_price=500-1000' 
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json'

In this above sample request there is filter filter=filter_price=500-1000 applied on the price column to get products in the price range of 500 to 1000.

By using this filter parameter, you can easily refine your search results based on specific criteria, such as color, size, price range, and more. This feature allows you to customize your search and find the products that best match your preferences and needs.

In summary, the filter parameter is a powerful tool that enables you to create, modify, and apply filters to your search requests. It provides a flexible and efficient way to narrow down your search results and find the products that you are looking for.

Chat Search

Chat-based search is a type of search where users can ask questions and receive answers through a chat interface, typically powered by artificial intelligence (AI) and natural language processing (NLP) technologies. Chat-based search can be implemented on a variety of platforms, including mobile apps, web browsers, and messaging apps.

With chat-based search, users can ask questions in a conversational style, using natural language. The AI-powered system then analyzes the question, understands the context and intent, and generates a response with list of products which suites the best for user query in a human-like manner. The system can also learn from the user's behavior and preferences, and improve its responses over time.

Below is the explaination and examples of usage for Chat Search offered by Zevi.AI

Endpoint: GET https://api.zevi.ai/2023-01/chat

Sample request

curl --request GET 'https://api.zevi.ai/2023-01/chat?q=lipstick&session_id=chat_session_identifier&store=63b5a4f23d3d68e12be783d9'
-H 'X-Zevi-Org-Id: 63b5a4f23d3d68e12be783d9' \
-H 'X-Zevi-Api-Key: 9a940c8f-4609-4fa8-acab-5f4d55facfef' \
-H 'Content-Type: application/json'

Param	Type	Description
`store`	String	Store name or Org Id (Required)
`q`	String	Any string which user enters (Required)
`session_id`	String	The session ID for the user's chat session (Required)

Sample response

{
  "products": [
    {
      "product_id": "74286",
      "title": "Beverage Cup",
      "description": "The glass-blown cup is the ideal companion for a cup of coffee or tea with the favorite homies. The tea is kept warm by the double-walled design, which makes the cup very comfortable to handle. Present tea in style with the beautiful, clear glass tea glasses, which are simple yet edgy. The glass cup is made of excellent quality material and is suitable for both formal as well as informal occasions. Set up the table with an elegant charm during an",
      "category1": "Home",
      "category2": "kitchenware & dining",
      "subcategory": "cup",
      "handle": "beverage-cup",
      "store_id": 227,
      "store_name": "Nestasia"
    },
    {
      "product_id": "74263",
      "title": "Milk Cup",
      "description": "Ceramic coffee cups in black are manufactured without any chemical processing and keeping in mind a need to carve a path for sustainable living. The elegant design and textured surface of the reusable coffee cup will compliment any table and home décor. Suit the needs of one's coffee table and be ready to be able to easily pair up the mugs with any snack plates of one's choice. The smooth matte finish of the mug prevents discoloration from takin",
      "category1": "Home",
      "category2": "kitchenware & dining",
      "subcategory": "cup",
      "handle": "milk-cup",
      "store_id": 227,
      "store_name": "Nestasia"
    },
    ...,
        ...
  ],
  "sentences": [
    "Get ready to make a statement with our stunning lipsticks! Here are some products for you:",
    "Our top pick for you is the \"Comfy Matte Liquid Lipstick\" - available in various shades, it offers a long-lasting, comfortable matte finish that you'll absolutely love!"
    ]
}

Metrics API

Action Items:

Calling an endpoint to get the sessionID and keep that sessionID consistent throughout the session.
Append that sessionID in args while calling the search API
Get the search response and make a note of the search identifier being returned by the api
Call the POST api to send data along with sessionID and searchIdentifier

Session API

What is a SESSION ID?

A session ID (session identifier) is a unique, randomly generated alphanumeric string that is assigned to a user session when they first access a website or web application. It is typically stored in a cookie or in the URL, and is used to identify the user during their session.

Session IDs are used to maintain stateful information about a user's interaction with a website or application, such as their login status, preferences, and shopping cart contents. They allow the server to associate all of the user's requests with the same session, so that it can provide analytical data.

Whenever a user session is starting, please call this API and get Search Session ID from our servers, and keep it consistent throughout that particular user session.

curl --location --request GET 'https://api.zevi.ai/2023-01/sessionIdentifier?store_name={client}'

Response :

{
    "session_identifier": "ewogICAgInNlc3Npb25faWQiOiAiVFAySDhUNDE2NTg1NTc0OTQuMzIzODIiLAogICAgImJ1Y2tldCI6ICJDQVRBTE9HTU9ERTpMRVhJQ0FMIgp9"
}

Modifications in the Search API

curl --location --request GET 'https://api.zevi.ai/2023-01/search?limit=25&usecache=False&store={client}&q=hair%20growth&session_id=ewogICAgInNlYXJjaF9pZCI6ICIwS0VLOThTMTY1ODIwNDI0My42NjU0Mzc1IiwKICAgICJidWNrZXQiOiAiQ0FUQUxPR01PREU6T1BFTiIKfQ=='

Note : session_id has been added to search request

No change in response structure, you will receive searchIdentifier as well from our end to be added in the metric API

Metric API

Call the below API on every product click that user is performing, appending the respective sessionIdentifier and searchIdentifier (returned by Search API)

curl --location --request POST 'https://api.zevi.ai/2023-01/metrics/add_search_event' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query":"oil",
        "product_id":"product ID", #Product ID of product being clicked on
        "rank":rank #Search Rank of the product,
    "store_name":"{client}",
    "searchIdentifier":"ewogICAgInNlYXJjaF9pZCI6ICJUTzE1MDc2MTY1ODIxMDg1OS41MDU3NDMzIgp9",
    "sessionIdentifier":"ewogICAgInNlc3Npb25faWQiOiAiRjZUMzQ1RTE2NTgyMTEzOTkuMTU5MDkyNyIsCiAgICAiYnVja2V0IjogIkNBVEFMT0dNT0RFOkxFWElDQUwiCn0",
        "timestamp": timestamp
}'

Please note : searchIdentifier and sessionIdentifier have been added to response structure

API Documentation

Authentication:​

Products:​

1. Create Products​

2. Get Products​

3. Update Products​

4. Upsert Products​

5. Delete Products​

Autocomplete​

What is Autocomplete?​

How can I use it?​

Sample request​

Sample response​

Search​

Sample request​

Sample response​

Filters​

What are filters?​

Customize fitlers​

Sample request with filter​

Filter parameter format: filter={filter_column}={value}​

Sample request with multiple filters on multiple columns​

Filter parameter format: filter={filter_column1}={value1}&filter={filter_column2}={value2}​

Sample request with multiple filters on same columns​

Filter parameter format: filter={filter_column1}={value1}&filter={filter_column1}={value2}​

Sample request with range based filters​

Filter parameter format: filter={filter_column}={min_value}-{max_value}​

Chat Search​

Sample request​

Sample response​

Metrics API​

Session API​

What is a SESSION ID?​

Modifications in the Search API​

Metric API​

Authentication:

Products:

1. Create Products

2. Get Products

3. Update Products

4. Upsert Products

5. Delete Products

Autocomplete

What is Autocomplete?

How can I use it?

Sample request

Sample response

Search

Sample request

Sample response

Filters

What are filters?

Customize fitlers

Sample request with filter

Filter parameter format: `filter={filter_column}={value}`

Sample request with multiple filters on multiple columns

Filter parameter format: `filter={filter_column1}={value1}&filter={filter_column2}={value2}`

Sample request with multiple filters on same columns

Filter parameter format: `filter={filter_column1}={value1}&filter={filter_column1}={value2}`

Sample request with range based filters

Filter parameter format: `filter={filter_column}={min_value}-{max_value}`

Chat Search

Sample request

Sample response

Metrics API

Session API

What is a SESSION ID?

Modifications in the Search API

Metric API