API Reference

SearchByte API

A single REST API to index your product catalog, run semantic and visual search, and track analytics — for any eCommerce platform.

Base URL

https://uat-kisna-search-service.ucxe8k.easypanel.host

Content-Type

application/json

Quick Example

curl -X GET "https://uat-kisna-search-service.ucxe8k.easypanel.host/search/?q=sustainable+yoga+mat" \
  -H "x-api-key: sk_your_api_key_here" \
  -H "X-Session-ID: sess_abc123"

Permissions

API keys can be scoped to specific permissions. Pass a permissions array when generating a key to restrict its access.

Permission	Description
`search:semantic`	Run semantic AI search queries
`search:fulltext`	Run full-text keyword search queries
`search:image`	Run visual image search queries
`products:upload`	Bulk-upload and index products
`products:update`	Update individual products
`products:delete`	Remove products from the index
`analytics:read`	Read analytics insights and reports
`analytics:write`	Send tracking events

Authentication

POST/auth/login

Login

Authenticate with your credentials to receive a JWT token. This token is required for management operations such as generating API keys.

Request Body

Name	Type	Description
emailreq	string	Your SearchByte account email
passwordreq	string	Your account password

Request

{
  "email": "you@example.com",
  "password": "••••••••"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "usr_01",
    "email": "you@example.com",
    "plan": "growth"
  },
  "expires_in": 259200
}

POST/auth/api-keyRequires JWT token

Generate API Key

Generate a scoped API key for use in your storefront integration. Keys can be restricted to specific permissions.

Headers

Name	Type	Description
Authorizationreq	string	Bearer <jwt_token>

Request Body

Name	Type	Description
namereq	string	Human-readable label for this key
permissions	string[]	Scope the key — e.g. ["search:semantic", "products:upload"]. Omit for full access.

Request

{
  "name": "My Storefront Key",
  "permissions": [
    "search:semantic",
    "search:fulltext",
    "analytics:write"
  ]
}

Response

{
  "api_key": "sk_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Storefront Key",
  "permissions": [
    "search:semantic",
    "search:fulltext",
    "analytics:write"
  ],
  "created_at": "2025-05-01T10:00:00Z"
}

Products

POST/products/uploadproducts:upload

Upload Products

Bulk-upload or sync your product catalog. Products are indexed immediately. Existing products with the same ID are updated.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key

Request Body

Name	Type	Description
idreq	string	Unique product ID from your platform
namereq	string	Product display name
description	string	Full description — used for semantic indexing
pricereq	number	Base price in specified currency
currency	string	ISO 4217 code. Default: USD
categories	string[]	Category hierarchy for filtering
images	object[]	Array of { url, alt } image objects
tags	string[]	Custom tags used in semantic matching
variants	object[]	Product variants with id, price, and attributes
in_stock	boolean	Inventory availability flag

Request

[
  {
    "id": "prod_001",
    "name": "EcoGrip Cork Mat 6mm",
    "description": "Sustainably sourced cork yoga mat with natural rubber base. Excellent grip, even when wet.",
    "price": 48,
    "currency": "USD",
    "categories": [
      "Sports",
      "Yoga"
    ],
    "images": [
      {
        "url": "https://cdn.example.com/mat.jpg",
        "alt": "Cork yoga mat"
      }
    ],
    "tags": [
      "eco-friendly",
      "yoga",
      "cork",
      "sustainable"
    ],
    "in_stock": true
  }
]

Response

{
  "indexed": 1,
  "updated": 0,
  "failed": 0,
  "errors": []
}

PUT/products/{id}products:update

Update Product

Update a single product by ID. Partial updates are supported — send only the fields you want to change.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key

Request

{
  "price": 44,
  "in_stock": false
}

Response

{
  "success": true,
  "id": "prod_001"
}

DELETE/products/{id}products:delete

Delete Product

Remove a product from the search index. The product will no longer appear in any search results.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key

Response

{
  "success": true,
  "id": "prod_001"
}

Search

GET/search/search:semantic

Semantic Search

AI-powered semantic search. Understands natural language, synonyms, typos, and shopper intent. Returns products ranked by relevance score.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key
X-User-ID	string	Opaque user identifier for analytics
X-Session-ID	string	Session identifier for analytics

Query Parameters

Name	Type	Description
qreq	string	Natural language search query
min_score	number	Minimum relevance threshold (0–1). Default: 0.3
limit	number	Max results. Default: 20, Max: 100

Response

{
  "results": [
    {
      "id": "prod_001",
      "name": "EcoGrip Cork Mat 6mm",
      "price": 48,
      "_score": 0.97,
      "categories": [
        "Sports",
        "Yoga"
      ],
      "images": [
        {
          "url": "https://cdn.example.com/mat.jpg"
        }
      ]
    }
  ],
  "total": 1,
  "query_time_ms": 68
}

GET/search/fulltextsearch:fulltext

Full-Text Search

Keyword-based full-text search using TF-IDF scoring. Best for exact term matching and autocomplete use cases.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key
X-User-ID	string	Opaque user identifier

Query Parameters

Name	Type	Description
qreq	string	Search query string
limit	number	Max results. Default: 20, Max: 100

Response

{
  "results": [
    {
      "id": "prod_001",
      "name": "EcoGrip Cork Mat 6mm",
      "price": 48,
      "_score": 4.32
    }
  ],
  "total": 1,
  "query_time_ms": 12
}

POST/search/imagesearch:image

Image Search

Upload an image to find visually similar products. Uses computer vision embeddings to match color, shape, texture, and style.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key
Content-Typereq	string	multipart/form-data

Request Body

Name	Type	Description
imagereq	File	Image file — JPG, PNG, or WEBP. Max 5 MB.
limit	number	Max results to return. Default: 10

Request

// multipart/form-data
FormData {
  image: <File>,  // JPG, PNG, or WEBP — max 5 MB
  limit: 10       // optional
}

Response

{
  "results": [
    {
      "id": "prod_042",
      "name": "Coastal Run Sneaker",
      "price": 44,
      "_score": 0.97
    },
    {
      "id": "prod_017",
      "name": "Urban Stride Low-Top",
      "price": 39,
      "_score": 0.94
    }
  ],
  "query_time_ms": 112
}

Analytics

POST/analytics/eventsanalytics:write

Track Event

Record a user interaction event (search, click, view). Used to power analytics dashboards and improve result ranking.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key

Request Body

Name	Type	Description
event_typereq	string	One of: search, click, view
query	string	The search query (for search events)
product_id	string	Product that was interacted with
user_id	string	Opaque user identifier
session_id	string	Session identifier
position	number	Result position clicked (1-indexed)

Request

{
  "event_type": "click",
  "query": "sustainable yoga mat",
  "product_id": "prod_001",
  "user_id": "usr_anon_abc123",
  "session_id": "sess_xyz789",
  "position": 1
}

Response

{
  "success": true
}

GET/analytics/insights/queriesanalytics:read

Query Insights

Per-query analytics including impressions, clicks, and CTR. Useful for identifying high-intent queries and catalog gaps.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key

Query Parameters

Name	Type	Description
from	string	Start date ISO 8601. Default: 30 days ago
to	string	End date ISO 8601. Default: now
limit	number	Top N queries to return. Default: 50

Response

{
  "queries": [
    {
      "query": "sustainable yoga mat",
      "searches": 342,
      "clicks": 289,
      "ctr": 0.845,
      "zero_results": 0
    },
    {
      "query": "blue sneakers size 10",
      "searches": 218,
      "clicks": 143,
      "ctr": 0.656,
      "zero_results": 12
    }
  ]
}

GET/analytics/insights/session-metricsanalytics:read

Session Metrics

Aggregate session-level engagement metrics to understand search depth and quality.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key

Response

{
  "avg_searches_per_session": 3.4,
  "avg_search_depth": 1.8,
  "engaged_sessions_percentage": 0.72,
  "total_sessions": 5840
}

GET/analytics/insights/user-countsanalytics:read

User Counts

Break down your user base into new, returning, and power users over a given time range.

Headers

Name	Type	Description
x-api-keyreq	string	Your SearchByte API key

Query Parameters

Name	Type	Description
from	string	Start date ISO 8601
to	string	End date ISO 8601

Response

{
  "all_users": 12840,
  "new_users": 3210,
  "returning_users": 8420,
  "power_users": 1210
}