SearchAF Logo

Search API#

Comprehensive guide to using the SearchAF search endpoints that power our answer engine.

Search Endpoint#

POST /projects/{project_id}/search

Execute semantic and keyword searches with advanced filtering and ranking to power intelligent answers.

Simple Query#

POST /api/v1/projects/{project_id}/search
Content-Type: application/json
X-API-Key: sk_live_...

{
  "query": "blue running shoes"
}

Response:

{
  "results": [
    {
      "id": "prod_123",
      "title": "Nike Air Zoom Pegasus - Blue",
      "description": "Lightweight running shoes...",
      "price": 129.99,
      "image_url": "https://...",
      "score": 0.95
    }
  ],
  "total": 42,
  "took_ms": 12,
  "query_id": "qry_abc123"
}

Search Parameters#

Query#

The search query text:

{
  "query": "wireless headphones"
}

Limit and Offset#

Control pagination:

{
  "query": "laptops",
  "limit": 20,
  "offset": 0
}
  • limit - Results per page (default: 20, max: 100)
  • offset - Number of results to skip (default: 0)

Filters#

Apply filters to narrow results:

{
  "query": "laptop",
  "filters": {
    "category": ["electronics", "computers"],
    "brand": ["Apple", "Dell"],
    "price_range": {
      "min": 500,
      "max": 2000
    },
    "in_stock": true
  }
}

Filter Types:

  • Array filters - Match any value in array
  • Range filters - Min/max numeric ranges
  • Boolean filters - True/false values
  • Text filters - Exact text matches

Facets#

Request faceted search results:

{
  "query": "shoes",
  "facets": ["category", "brand", "color", "size"]
}

Response includes facet counts:

{
  "results": [...],
  "facets": {
    "category": {
      "running": 42,
      "casual": 28,
      "formal": 15
    },
    "brand": {
      "Nike": 35,
      "Adidas": 30,
      "Puma": 20
    }
  }
}

Sorting#

Customize result ordering:

{
  "query": "laptops",
  "sort": [
    { "field": "_score", "order": "desc" },
    { "field": "price", "order": "asc" }
  ]
}

Sort Fields:

  • _score - Relevance score (default)
  • price - Product price
  • created_at - Creation date
  • popularity - Popularity metric
  • Custom fields from your schema

Control the balance between semantic and keyword search:

{
  "query": "running shoes",
  "search_mode": "hybrid",
  "semantic_weight": 0.7
}

Search Modes:

  • hybrid - Combine semantic and keyword (default)
  • semantic - AI-powered vector search only
  • keyword - Traditional keyword search only

Semantic Weight:

  • 0.0 - Pure keyword search
  • 0.5 - Equal balance
  • 1.0 - Pure semantic search

Boosting#

Boost specific fields or values:

{
  "query": "laptop",
  "boost": {
    "fields": {
      "title": 2.0,
      "description": 1.0,
      "brand": 1.5
    },
    "values": {
      "brand": {
        "Apple": 1.3,
        "Dell": 1.1
      }
    }
  }
}

Personalization#

Include user context for personalized results:

{
  "query": "headphones",
  "user_context": {
    "user_id": "usr_123",
    "preferences": {
      "brands": ["Sony", "Bose"],
      "price_range": "premium"
    },
    "history": {
      "viewed": ["prod_456", "prod_789"],
      "purchased": ["prod_234"]
    }
  }
}

Search Features#

Autocomplete#

Get query suggestions for autocomplete:

POST /api/v1/projects/{project_id}/autocomplete
Content-Type: application/json
X-API-Key: sk_live_...

{
  "query": "blue run",
  "limit": 5
}

Response:

{
  "suggestions": [
    "blue running shoes",
    "blue runners",
    "blue running jacket"
  ]
}

Similar Products#

Find products similar to a specific item:

POST /api/v1/projects/{project_id}/similar
Content-Type: application/json
X-API-Key: sk_live_...

{
  "product_id": "prod_123",
  "limit": 10
}

Recommendations#

Get personalized product recommendations:

POST /api/v1/projects/{project_id}/recommendations
Content-Type: application/json
X-API-Key: sk_live_...

{
  "user_id": "usr_123",
  "limit": 10,
  "context": {
    "page": "homepage",
    "category": "electronics"
  }
}

Search Analytics#

Tracking Queries#

Track search queries for analytics:

{
  "query": "wireless mouse",
  "track": true,
  "tracking_data": {
    "user_id": "usr_123",
    "session_id": "ses_abc",
    "page": "search"
  }
}

Click Tracking#

Track product clicks to improve ranking:

POST /api/v1/projects/{project_id}/track/click
Content-Type: application/json
X-API-Key: sk_live_...

{
  "query_id": "qry_abc123",
  "product_id": "prod_456",
  "position": 3,
  "user_id": "usr_123"
}

Conversion Tracking#

Track conversions (purchases):

POST /api/v1/projects/{project_id}/track/conversion
Content-Type: application/json
X-API-Key: sk_live_...

{
  "query_id": "qry_abc123",
  "product_id": "prod_456",
  "user_id": "usr_123",
  "revenue": 129.99
}

Performance Optimization#

Caching#

SearchAF automatically caches common queries. You can control caching:

{
  "query": "popular search",
  "cache_ttl": 300
}

Field Selection#

Limit returned fields for faster responses:

{
  "query": "laptops",
  "fields": ["id", "title", "price", "image_url"]
}

Timeout#

Set query timeout:

{
  "query": "complex search",
  "timeout_ms": 1000
}

Error Handling#

Invalid Query#

{
  "type": "https://searchaf-api.antfly.io/errors/invalid-query",
  "title": "Invalid Query",
  "status": 400,
  "detail": "Query parameter is required"
}

No Results#

{
  "results": [],
  "total": 0,
  "took_ms": 5,
  "query_id": "qry_abc123"
}

Timeout#

{
  "type": "https://searchaf-api.antfly.io/errors/timeout",
  "title": "Query Timeout",
  "status": 504,
  "detail": "Query exceeded timeout limit"
}

Example Implementation#

interface SearchParams {
  query: string;
  limit?: number;
  offset?: number;
  filters?: Record<string, any>;
  facets?: string[];
}

async function search(
  projectId: string,
  params: SearchParams
) {
  const response = await fetch(
    `https://searchaf-api.antfly.io/api/v1/projects/${projectId}/search`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.SEARCHAF_API_KEY!,
      },
      body: JSON.stringify(params),
    }
  );

  if (!response.ok) {
    throw new Error(`Search failed: ${response.statusText}`);
  }

  return response.json();
}

// Usage
const results = await search('proj_123', {
  query: 'blue running shoes',
  limit: 20,
  filters: {
    price_range: { min: 50, max: 200 },
    in_stock: true,
  },
  facets: ['brand', 'size', 'color'],
});

Next Steps#