Basic Search

The Seekora Search API lets you query your product catalog and retrieve relevant results with a single request. This guide covers the core search endpoint, request parameters, and response structure.

Authentication

All requests require two headers:

Header	Description
x-storeid	Your store identifier
x-storesecret	Your read-only store secret

POST /v1/search

The primary search endpoint accepts a JSON body with your query and parameters.

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": "running shoes",
    "per_page": 5,
    "page": 1
  }'

Response

{
  "found": 142,
  "page": 1,
  "per_page": 5,
  "hits": [
    {
      "document": {
        "id": "prod_8291",
        "title": "Ultraboost Running Shoe",
        "price": 129.99,
        "image_url": "https://cdn.example.com/images/ultraboost.jpg",
        "category": "Footwear > Running",
        "brand": "Adidas",
        "in_stock": true
      },
      "highlight": {
        "title": "<mark>Running</mark> <mark>Shoe</mark>"
      },
      "text_match_score": 1048576
    },
    {
      "document": {
        "id": "prod_3047",
        "title": "Fresh Foam Running Shoes",
        "price": 89.99,
        "image_url": "https://cdn.example.com/images/fresh-foam.jpg",
        "category": "Footwear > Running",
        "brand": "New Balance",
        "in_stock": true
      },
      "highlight": {
        "title": "Fresh Foam <mark>Running</mark> <mark>Shoes</mark>"
      },
      "text_match_score": 1032192
    }
  ]
}

Response Fields

Field	Type	Description
found	integer	Total number of matching documents
hits	array	Array of matching documents for the current page
hits[].document	object	The full product document (or a subset if return_fields is used)
hits[].highlight	object	Highlighted field values with matching terms wrapped in <mark> tags
hits[].text_match_score	integer	Relevance score for ranking
page	integer	Current page number
per_page	integer	Number of results per page

GET /v1/search

You can also issue search requests as GET with query parameters. This is useful for simple queries or browser-based testing.

curl -G https://api.seekora.ai/v1/search \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  --data-urlencode "q=running shoes" \
  --data-urlencode "per_page=5" \
  --data-urlencode "page=1"

The response format is identical to the POST variant.

Required Parameters

Parameter	Type	Description
q	string	The search query string. Use * to match all documents.

Pagination Parameters

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

Controlling Returned Fields

return_fields

Specify which fields to include in each hit. This reduces payload size when you only need a few fields.

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": "leather jacket",
    "return_fields": ["title", "price", "image_url", "id"]
  }'

Response documents will only contain the specified fields:

{
  "found": 38,
  "page": 1,
  "per_page": 10,
  "hits": [
    {
      "document": {
        "id": "prod_1120",
        "title": "Classic Leather Moto Jacket",
        "price": 249.99,
        "image_url": "https://cdn.example.com/images/moto-jacket.jpg"
      }
    }
  ]
}

omit_fields

Exclude specific fields from the response. Useful when documents contain large fields like full descriptions that you do not need for a listing 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": "leather jacket",
    "omit_fields": ["long_description", "metadata"]
  }'

Limiting Which Fields Are Searched

search_fields

By default, the query is matched against all searchable fields in your schema. Use search_fields to restrict which fields the query runs against.

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",
    "search_fields": ["brand", "title"]
  }'

This ensures the query "Nike" only matches against the brand and title fields, ignoring descriptions or other text fields.

field_weights

Boost certain fields so that matches in those fields rank higher. Weights are relative integers -- a field with weight 3 contributes three times as much to the relevance score as a field with weight 1.

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": "organic cotton t-shirt",
    "search_fields": ["title", "description", "tags"],
    "field_weights": {
      "title": 5,
      "tags": 3,
      "description": 1
    }
  }'

In this example, a match in title is weighted five times more than a match in description, and a match in tags is weighted three times more. This helps surface products where the query terms appear in the most relevant fields.

POST /v1/multi-search

Batch up to 10 independent search queries in a single HTTP request. Each query can have its own filters, sorting, pagination, and facets. This is useful for federated search (e.g., products + articles + suggestions on one page) or loading multiple collections simultaneously.

curl -X POST https://api.seekora.ai/v1/multi-search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-store-secret" \
  -d '{
    "queries": [
      {
        "q": "laptop",
        "per_page": 5,
        "filter_by": "category:Electronics"
      },
      {
        "q": "laptop bag",
        "per_page": 3,
        "sort_by": "price:asc"
      }
    ]
  }'

Response

The response contains a results array with one entry per query, in the same order as the input.

{
  "results": [
    {
      "found": 142,
      "page": 1,
      "per_page": 5,
      "hits": [ ... ]
    },
    {
      "found": 28,
      "page": 1,
      "per_page": 3,
      "hits": [ ... ]
    }
  ]
}

Parameters

Parameter	Type	Description
queries	array	Array of search query objects (max 10). Each object accepts the same parameters as the single search endpoint.

Each query object supports all parameters from POST /v1/search (q, per_page, page, filter_by, facet_by, sort_by, return_fields, etc.).

Use Cases

• Federated search: Search products, articles, and FAQs in one request
• Collection pages: Load "New Arrivals", "Best Sellers", and "On Sale" sections simultaneously
• Comparison: Run the same query with different filters side by side

Next Steps

• Filtering and Facets -- narrow results with filters and retrieve facet counts.
• Sorting and Pagination -- control result ordering and page through large result sets.
• Advanced Search -- typo tolerance, snippets, prefix matching, and more.