Sorting and Pagination

Control the order of search results and navigate through large result sets with sorting and pagination parameters.

Sorting with sort_by

By default, results are sorted by relevance score. Use sort_by to sort by one or more fields.

Single Field Sort

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "winter jacket",
    "sort_by": "price:asc"
  }'

Sort Direction

Suffix	Description
:asc	Ascending (lowest first)
:desc	Descending (highest first)

Multiple Sort Fields

Separate multiple sort fields with commas. Results are sorted by the first field, with ties broken by the second field, and so on.

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "winter jacket",
    "sort_by": "price:asc,rating:desc"
  }'

This returns winter jackets sorted by price (lowest first), with products at the same price sorted by rating (highest first).

Common Sort Fields

Field	Example	Use Case
price	price:asc	Price low to high
price	price:desc	Price high to low
rating	rating:desc	Top rated first
created_at	created_at:desc	Newest arrivals
popularity	popularity:desc	Best sellers
title	title:asc	Alphabetical

Pagination

Parameters

Parameter	Type	Default	Description
page	integer	1	The page number to retrieve (1-indexed)
per_page	integer	10	Number of results per page (max 250)

Basic Pagination

# First page
curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "t-shirt",
    "per_page": 24,
    "page": 1
  }'

# Second page
curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "t-shirt",
    "per_page": 24,
    "page": 2
  }'

Calculating Total Pages

Use the found field from the response to calculate the total number of pages:

total_pages = ceil(found / per_page)

For example, if found is 142 and per_page is 24, there are ceil(142 / 24) = 6 pages.

Grouping Results

Group results by a field value to show a fixed number of products per group. This is useful for category overview pages or search results that span multiple product types.

Parameters

Parameter	Type	Description
group_field	string	The field to group results by
group_size	integer	Number of results to show per group

Example: Group by Category

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "Nike",
    "group_field": "category",
    "group_size": 3,
    "per_page": 12
  }'

Response:

{
  "found": 210,
  "hits": [
    {
      "group_key": "Running",
      "documents": [
        {
          "document": {
            "id": "prod_8291",
            "title": "Nike Air Zoom Pegasus",
            "price": 119.99,
            "category": "Running"
          }
        },
        {
          "document": {
            "id": "prod_8305",
            "title": "Nike React Infinity",
            "price": 159.99,
            "category": "Running"
          }
        },
        {
          "document": {
            "id": "prod_8412",
            "title": "Nike Free Run 5.0",
            "price": 99.99,
            "category": "Running"
          }
        }
      ]
    },
    {
      "group_key": "Basketball",
      "documents": [
        {
          "document": {
            "id": "prod_7201",
            "title": "Nike LeBron 21",
            "price": 199.99,
            "category": "Basketball"
          }
        },
        {
          "document": {
            "id": "prod_7215",
            "title": "Nike KD 16",
            "price": 159.99,
            "category": "Basketball"
          }
        },
        {
          "document": {
            "id": "prod_7220",
            "title": "Nike Giannis Immortality",
            "price": 89.99,
            "category": "Basketball"
          }
        }
      ]
    }
  ]
}

Each group contains up to group_size documents. This lets you display a "Top 3 Running shoes, Top 3 Basketball shoes, ..." layout without making multiple API calls.

Combining Sorting, Pagination, and Filters

All parameters work together. Here is a complete example that filters, sorts, and paginates:

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "q": "dress",
    "filter_by": "category:Dresses && price:[30..150] && in_stock:true",
    "sort_by": "price:asc,rating:desc",
    "per_page": 24,
    "page": 1,
    "facet_by": "brand,color,size"
  }'

Next Steps

• Advanced Search -- typo tolerance, snippets, prefix matching, and more.