Skip to main content

Quick Start

This guide walks you through indexing products and running your first search query. By the end, you will have a working search experience with filters.

Prerequisites​

  • A Seekora store created via the Dashboard.
  • Your Store ID, Read Secret, and Write Secret from Store Settings > API Keys. See the Authentication guide for details.

Step 1: Define a Schema​

A schema tells Seekora how to index and search your data. Define the fields your products will have.

curl -X POST https://api.seekora.ai/api/v1/stores/your-store-id/schema \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-store-write-secret: your-write-secret" \
  -d '{
    "fields": [
      { "name": "title", "type": "string", "facet": false },
      { "name": "description", "type": "string", "facet": false },
      { "name": "price", "type": "float", "facet": true },
      { "name": "brand", "type": "string", "facet": true },
      { "name": "category", "type": "string", "facet": true },
      { "name": "image_url", "type": "string", "facet": false },
      { "name": "in_stock", "type": "bool", "facet": true }
    ]
  }'

Response:

{
  "success": true,
  "message": "Schema updated successfully"
}

Step 2: Index Documents​

Index a batch of products using the bulk documents endpoint.

curl -X POST https://api.seekora.ai/api/v1/stores/your-store-id/documents/bulk \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-store-write-secret: your-write-secret" \
  -d '{
    "documents": [
      {
        "id": "prod-001",
        "title": "Trail Runner Pro",
        "description": "Lightweight trail running shoes with superior grip and cushioning.",
        "price": 129.99,
        "brand": "ActiveStride",
        "category": "Running Shoes",
        "image_url": "https://example.com/images/trail-runner-pro.jpg",
        "in_stock": true
      },
      {
        "id": "prod-002",
        "title": "Urban Jogger",
        "description": "Comfortable everyday running shoes for road and treadmill use.",
        "price": 89.99,
        "brand": "ActiveStride",
        "category": "Running Shoes",
        "image_url": "https://example.com/images/urban-jogger.jpg",
        "in_stock": true
      },
      {
        "id": "prod-003",
        "title": "Classic Oxford Shirt",
        "description": "Button-down oxford shirt in 100% cotton. Slim fit.",
        "price": 59.99,
        "brand": "ThreadCraft",
        "category": "Shirts",
        "image_url": "https://example.com/images/classic-oxford.jpg",
        "in_stock": true
      },
      {
        "id": "prod-004",
        "title": "Performance Tank Top",
        "description": "Moisture-wicking tank top for running and gym workouts.",
        "price": 34.99,
        "brand": "ActiveStride",
        "category": "Tops",
        "image_url": "https://example.com/images/performance-tank.jpg",
        "in_stock": false
      }
    ]
  }'

Response:

{
  "success": true,
  "indexed": 4,
  "errors": []
}

Search for products using the read secret.

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -d '{
    "q": "running shoes"
  }'

Response:

{
  "hits": [
    {
      "id": "prod-001",
      "title": "Trail Runner Pro",
      "description": "Lightweight trail running shoes with superior grip and cushioning.",
      "price": 129.99,
      "brand": "ActiveStride",
      "category": "Running Shoes",
      "image_url": "https://example.com/images/trail-runner-pro.jpg",
      "in_stock": true
    },
    {
      "id": "prod-002",
      "title": "Urban Jogger",
      "description": "Comfortable everyday running shoes for road and treadmill use.",
      "price": 89.99,
      "brand": "ActiveStride",
      "category": "Running Shoes",
      "image_url": "https://example.com/images/urban-jogger.jpg",
      "in_stock": true
    }
  ],
  "found": 2,
  "page": 1,
  "total_pages": 1
}

Step 4: Add Filters​

Retrieve available filter facets for a query. This returns the values your users can filter by.

curl -X POST https://api.seekora.ai/v1/filters \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -d '{
    "q": "running shoes"
  }'

Response:

{
  "facets": {
    "brand": [
      { "value": "ActiveStride", "count": 2 }
    ],
    "category": [
      { "value": "Running Shoes", "count": 2 }
    ],
    "price": {
      "min": 89.99,
      "max": 129.99
    },
    "in_stock": [
      { "value": "true", "count": 2 }
    ]
  }
}

You can then apply filters in your search request:

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -d '{
    "q": "running shoes",
    "filters": {
      "price": { "min": 50, "max": 100 }
    }
  }'

This returns only the Urban Jogger (priced at $89.99), filtering out the Trail Runner Pro.

Next Steps​