README

To set up it, simply install EPICA application in your Shopify store and feed will configure automatically. Make sure that you complete this step before usage and reading this document.

Validation

The main endpoint for search(/api/v1/search) do not need authorization, but also need a write_key which you can find in our platform in account settings. As EPICA company client, you can also have an auth token. You can read more about it here.

Public API (use write_key)

Shopify product has several variants and when you are searching, we display most relevant of them. This public endpoint does not need any auth. There are GET and POST methods here:

  • GET method works fast but returns only 6 most relevant products and some extra information about it. We use it in the search widget

  • POST method works a little bit longer but has extra features like filtering and paging. You can see it in full search page

Purpose

Search

Endpoint

/api/v1/search

Method

GET
POST

(GET) Request params


(GET) Request optional params

(GET) Response fields


(GET) Response example

query: (type: string) search query
write_key: (type: string) company write_key, system field

anonymous_id: (type: uuid) person identifier, generated by epica.js  
prev_query: (type: string) previous search query

autocomplete_items: (type: array(string)) query suggestions 
found_products: (type: array(object)) relevant items from feed
query: (type: string) search query
found_categories: (type: array(object)) relevant categories from feed

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 { "found_products": [ { "price": 51.0, "title": "INSULAR Mummy Diaper Backpack Fashionable Large Capacity Mother Bag Multifunctional Travel Baby Backpack bag Nappy Bags", "score": 191.12119, "url": "https://demo-ec.epica.ai/products/insular-mummy-diaper-backpack-fashionable-large-capacity-mother-bag-multifunctional-travel-baby-backpack-stroller-bag-nappy-bags?variant=26562489581632", "discount_percent": 0, "image": "https://cdn2.shopify.com/s/files/1/0055/3143/5072/products/product-image-816957997.jpg?v=1552300692", "sku": "3207712833600_26562489581632", "discount": 51.0 }, { "price": 64.0, "title": "Diaper bag nappy", "score": 191.57248, "url": "https://demo-ec.epica.ai/products/baby-stroller-bag-fashion-mummy-bags-large-diaper-bag-backpack-baby-organizer-maternity-bags-for-mother-handbag-nappy-backpack?variant=26562746449984", "discount_percent": 0, "image": "https://cdn2.shopify.com/s/files/1/0055/3143/5072/products/product-image-508608478.jpg?v=1552300978", "sku": "3207756709952_26562746449984", "discount": 64.0 } ], "found_products_count": 44, "autocomplete_items": [ "red bag dollar", "red bags", "bag" ], "query": "red bag", "found_categories": [ { "url": "https://demo-ec.epica.ai/collections/home-page", "title": "Home Page" }, { "url": "https://demo-ec.epica.ai/collections/diaper-bags", "title": "Diaper Bags" } ] }

(POST) Request body params


(POST) Request body optional params


(POST) Response fields

query: (type: string) search query
write_key: (type: string) company write_key, system field

anonymous_id: (type: uuid) person identifier, generated by epica.js  
prev_query: (type: string) previous search query
filters: (type: object) search filters, more info in /api/v1/search/filter
page: (type: int) pagination

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 { "found_products_count": 44, "query": "red bag", "found_products": [ { "price": 51.0, "title": "INSULAR Mummy Diaper Backpack Fashionable Large Capacity Mother Bag Multifunctional Travel Baby Backpack bag Nappy Bags", "score": 191.12119, "url": "https://demo-ec.epica.ai/products/insular-mummy-diaper-backpack-fashionable-large-capacity-mother-bag-multifunctional-travel-baby-backpack-stroller-bag-nappy-bags?variant=26562489581632", "discount_percent": 0, "image": "https://cdn2.shopify.com/s/files/1/0055/3143/5072/products/product-image-816957997.jpg?v=1552300692", "sku": "3207712833600_26562489581632", "discount": 51.0 }, ... { "price": 61.0, "title": "Insular Mummy Maternity Diaper Bag Large Capacity Baby Stroller Bag Travel Nappy Backpack Designer Nursing Bag For Baby Care", "score": 23.472298, "url": "https://demo-ec.epica.ai/products/insular-mummy-maternity-diaper-bag-large-capacity-baby-stroller-bag-travel-nappy-backpack-designer-nursing-bag-for-baby-care?variant=26562233925696", "discount_percent": 0, "image": "https://cdn2.shopify.com/s/files/1/0055/3143/5072/products/product-image-786499954.jpg?v=1552300411", "sku": "3207670890560_26562233925696", "discount": 61.0 } ], "page": 1, "filters": [ { "max": 282.0, "title": "Price", "current_max": 282.0, "type": "price", "current_min": 1.0, "min": 1.0 }, { "based_on": "tag", "position": 1, "title": "All tag", "filter": "", "type": "filter", "values": [ { "name": "0", "count": 1 }, ... { "name": "car seats", "count": 1 } ], "id": 1 }, { "based_on": "collection", "position": 2, "title": "All collection", "filter": "", "type": "filter", "values": [ { "name": "Diaper Bags", "count": 23 }, { "name": "Highchairs & Booster Seats", "count": 1 }, { "name": "Home Page", "count": 44 } ] ... } ], "total_pages": 3 }

Errors

  • 401: unauthorized. It means that you have not passed JWT auth. More info in  API Authentication

Curl Example

1 GET: curl -X GET -H "Content-Type: application/json" "https://api.epica.ai/api/v1/search?query=red%20stroller&write_key=6682adba374255dc50091d6d3702f36d"

Platform API (need auth_token)

Filters

You can create your own filters based on search fields. There are some default filters after the initialization of the search app. Here is an example of how we use it

Purpose

Filters for full search

Endpoint

/api/v1/search/filters

Method

GET
POST
PUT
DELETE

(GET) Response fields


(GET) Response example

filters: (type: array(object)) list of all filters
based_on: (type: array(object)) list of objects used to create filters

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 {    "error": null,    "message": "Ok",    "data": {       "based_on": [          {             "field_name": "tag",             "id": 1          },          {             "field_name": "brand",             "id": 3          },          {             "field_name": "collection",             "id": 2          },          {             "field_name": "color",             "id": 5          },          {             "field_name": "size",             "id": 4 }       ],       "filters": [          {             "filter": "",             "position": 3,             "based_on_id": 5,             "id": 14,             "updated_at": "2019-02-20T17:52:47.083033",             "title": "Color",             "created_at": "2019-02-20T17:52:47.083023",             "status": false          },          {             "filter": "",             "position": 0,             "based_on_id": 1,             "id": 11,             "updated_at": "2019-02-20T17:52:47.083033",             "title": "Tag",             "created_at": "2019-02-20T17:52:47.083023",             "status": true          }          ...       ]    } }

 

(POST/PUT) Request body params

(POST/PUT) Request body example

 

 

 

 

 

 

 

filters: (type: array(object)) list of new filters

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 [    {       "title": "Collection filter",       "filter": "",       "status": true,       "based_on_id": 2,       "position": 5    },    {       "title": "Brand marko",       "filter": "Marco",       "status": true,       "based_on_id": 3,       "position": 6    }, ]

(DELETE) Request body params

(DELETE) Request body example

 

filter_ids: (type: array(int)) list of filter ids to be delete

Errors

  • 401: unauthorized. It means that you have not passed JWT auth. More info in  API Authentication

Curl Example

1 curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <auth_token>" "https://api.epica.ai/api/v1/search/filters"

Filter values

This endpoint is used to get all possible values for the filter

Purpose

Setup fields for search

Endpoint

/api/v1/search/filter/items/{filter_id}

Method

GET

(GET) Request URL example

(GET) Response fields

(GET) Response example

/api/v1/search/filter/items/1


filter_values: (type: array(object)) list of filter values

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 {    "filter_values": [       {          "count": 3,          "name": "Baby Jogger"       },       {          "count": 14,          "name": "Bebesit"       },       {          "count": 3,          "name": "Britax"       }       ...    ] }

Errors

  • 401: unauthorized. It means that you have not passed JWT auth. More info in API Authentication

Curl Example

1 curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <auth_token>" "https://api.epica.ai/api/v1/search/filter/items/"

Fields setup

By default, all fields are included in the search, but you can exclude some of them. The endpoint is used in settings.

Purpose

Setup fields for search

Endpoint

/api/v1/search/fields

Method

GET
PUT

(GET) Response fields

(GET) Response example

search_fields: (type: array(object)) list of fields available for search

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 {    "error": null,    "message": "Ok",    "data": {       "search_fields": [          {             "power": 1,             "id": 2,             "updated_at": "2019-02-19T21:31:35.228901",             "title": "Description",             "created_at": "2019-02-19T21:31:35.228885",             "status": false          },          {             "power": 1,             "id": 1,             "updated_at": "2019-02-19T21:31:35.228901",             "title": "Title",             "created_at": "2019-02-19T21:31:35.228885",             "status": true          }          ...       ]    } }

(PUT) Request body params

(PUT) Request body example

 

 

 

fields: (type: array(object)) list of the field which should be modified

1 2 3 4 5 6 7 8 9 10 {    "fields": [       {          "id": 1,          "status": false       },       ...    ] }

Errors

  • 401: unauthorized. It means that you have not passed JWT auth. More info in  API Authentication

Curl Example

1 curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <auth_token>" "https://api.epica.ai/api/v1/search/fields"

 Info

It should take time between installation and usage

Purpose

Check the status of the search

Endpoint

/api/v1/search/info

Method

GET

(GET) Response body fields

availability: (type: bool) is search app ready or not

Errors

  • 401: unauthorized. It means that you have not passed JWT auth. More info in  API Authentication

Curl Example

1 curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <auth_token>" "https://api.epica.ai/api/v1/search/info"

Config

We are planning a lot of configs. Now there is only one serve config display_not_active_products.

Purpose

Store config

Endpoint

/api/v1/search/config

Method

GET

PUT

(GET) Response body fields

display_not_active_products: (type: bool, default: false) filter by field active. Display all products if false

(PUT) Request params

display_not_active_products: (type: bool, default: false) filter by field active. Display all products if false

Errors

  • 401: unauthorized. It means that you have not passed JWT auth. More info in  API Authentication

Curl Example

1 curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <auth_token>" "https://api.epica.ai/api/v1/search/config"

 Reindex content

It is admin v0 endpoint. It's used for all components rebuilding (feed, models, recommenders)

Purpose

Full rebuild

Endpoint

/api/v0/search/reindex

Method

POST

(POST) Request body params

schema: (type: string) company schema name. system field
tenant_id: (type: int) company id. system field
language: (type: string) language of feed content

Errors

  • 401: unauthorized. It means that you have not passed JWT auth. More info in  API Authentication