Semantic Search

Intufind uses AI-powered semantic search to understand user intent and find relevant results — even when exact keywords don't match.

How It Works

Traditional search matches exact keywords. Semantic search understands meaning:

Query	Keyword Search	Semantic Search
"comfortable shoes for walking"	Matches "comfortable", "shoes", "walking"	Finds walking shoes, hiking boots, orthopedic footwear
"something for my headache"	Matches "headache" only	Finds pain relievers, aspirin, ibuprofen
"gift for coffee lover"	Matches "gift", "coffee"	Finds coffee makers, mugs, beans, grinders

Indexing Content

For optimal search results, provide rich, descriptive content when indexing:

curl -X POST https://api.intufind.com/products \
  -H "Authorization: Bearer if_sk_xxx" \
  -H "X-Workspace-ID: my-store-com" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "hiking-boots-pro",
    "name": "TrailMaster Pro Hiking Boots",
    "content": "Professional-grade hiking boots designed for outdoor enthusiasts. Features waterproof Gore-Tex lining, Vibram outsoles for superior grip, and cushioned midsoles for all-day comfort.",
    "excerpt": "Waterproof hiking boots with superior grip and comfort",
    "categories": ["Footwear", "Hiking", "Outdoor"],
    "tags": ["waterproof", "hiking", "boots", "trail"],
    "attributes": {
      "material": ["Leather", "Gore-Tex"],
      "activity": ["Hiking", "Trekking", "Backpacking"]
    }
  }'

import { createClient, upsertProduct } from '@intufind/ai-sdk';

const client = createClient({
  baseUrl: 'https://api.intufind.com',
  auth: process.env.INTUFIND_SECRET_KEY!,
});

await upsertProduct({
  client,
  body: {
    id: 'hiking-boots-pro',
    name: 'TrailMaster Pro Hiking Boots',
    content: 'Professional-grade hiking boots designed for outdoor enthusiasts...',
    categories: ['Footwear', 'Hiking', 'Outdoor'],
    attributes: {
      material: ['Leather', 'Gore-Tex'],
      activity: ['Hiking', 'Trekking'],
    },
  },
});

Search Queries

Basic Search

curl -X POST https://api.intufind.com/products/search \
  -H "Authorization: Bearer if_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "comfortable shoes for long walks", "limit": 20}'

Filtered Search

Combine semantic search with structured filters:

curl -X POST https://api.intufind.com/products/search \
  -H "Authorization: Bearer if_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "waterproof outdoor gear",
    "filters": {
      "categories": ["Outdoor", "Hiking"],
      "price_min": 50,
      "price_max": 200,
      "stock_status": "instock"
    },
    "limit": 20
  }'

Content Search

Search blog posts, articles, and pages:

curl -X POST https://api.intufind.com/posts/search \
  -H "Authorization: Bearer if_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "how to prepare for a hiking trip", "limit": 10}'

Faceted Search

Faceted search returns aggregated counts alongside results, enabling dynamic filter UIs.

curl -X POST https://api.intufind.com/products/search \
  -H "Authorization: Bearer if_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "running shoes",
    "includeFacets": true,
    "facetFields": ["categories", "brands", "price_ranges", "attributes.color"],
    "facetSize": 20
  }'

Available Facet Fields

Field	Description
categories	Product category counts
brands	Brand distribution
stock_status	In stock / out of stock counts
on_sale	Sale vs regular price counts
featured	Featured product counts
type	Product type distribution
price_ranges	Pre-defined price range buckets
attributes.{key}	Custom attribute values (e.g., attributes.color)
metadata.{key}	Custom metadata fields

Building a Filter UI

When users apply filters, facets update to reflect the filtered subset:

import { createClient, searchProducts } from '@intufind/ai-sdk';

const client = createClient({
  baseUrl: 'https://api.intufind.com',
  auth: process.env.INTUFIND_SECRET_KEY!,
});

const { data } = await searchProducts({
  client,
  body: {
    text: 'running shoes',
    filters: { brands: ['Nike'] },
    includeFacets: true,
    facetFields: ['categories', 'attributes.color'],
  },
});

// data.facets.categories → [{key: "Running", count: 45}, ...]
// data.facets["attributes.color"] → [{key: "Black", count: 23}, ...]

Handling Zero Results

When a search returns no results, fall back to trending recommendations:

import { searchProducts, getTrendingRecommendations } from '@intufind/ai-sdk';

const { data } = await searchProducts({
  client,
  body: { text: query },
});

if (!data?.results?.length) {
  const trending = await getTrendingRecommendations({
    client,
    body: { limit: 8 },
  });
  // Show "No results found. Here are popular items:" with trending.data
}

Indexing Best Practices

Write for Humans, Not Keywords

❌  "hiking boots boots for hiking waterproof boots hiking shoes"
✅  "These professional hiking boots keep your feet dry on rainy trails
    while providing excellent ankle support for rough terrain."

Include Synonyms Naturally

"Running shoes (also known as trainers or sneakers) designed for
both casual jogging and serious marathon training."

Describe Use Cases

"Perfect for weekend hikers, backpackers on multi-day trips, and
outdoor professionals who need reliable footwear."

Use Descriptive Attributes

{
  "attributes": {
    "best_for": ["Trail Running", "Day Hikes", "Light Backpacking"],
    "features": ["Waterproof", "Breathable", "Lightweight"],
    "user_type": ["Beginner", "Intermediate", "Advanced"]
  }
}

Performance Tips

1. Cache frequent searches — popular queries benefit from a short TTL cache
2. Use pagination — don't request more results than needed
3. Filter early — apply filters to reduce the result set before ranking
4. Index strategically — only index content that should be searchable

Next Steps

• API Reference — Full search endpoint documentation
• AI Chat — Conversational search and discovery
• Widget Search — Drop-in search widget