Knowledge Search API

Perform semantic search across your chatbot’s knowledge base using vector embeddings, keyword matching, or the full smart retrieval pipeline.

Endpoint

POST /api/v1/chatbots/:chatbotId/search

Required scope: knowledge:search

Rate limit: 30 requests per minute (in addition to the standard 100/min API key limit).

Request Body

Search Modes

Vector Search ("vector")

Pure semantic similarity using OpenAI embeddings. Fast and effective for most use cases.

Best for: Natural language questions, conceptual queries.

Hybrid Search ("hybrid")

Combines vector similarity (70%) with full-text keyword search (30%). Catches results that semantic search might miss.

Best for: Queries with specific terms, product names, or technical jargon.

Smart Search ("smart")

Full retrieval pipeline: multi-query expansion → hybrid search → AI reranking. Most accurate but slower.

Best for: Complex questions, production chatbot queries, maximum accuracy.

Examples

curl -X POST "https://trigglio.com/api/v1/chatbots/CHATBOT_ID/search" \
  -H "Authorization: Bearer tr_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I cancel my subscription?",
    "limit": 5,
    "mode": "hybrid",
    "threshold": 0.4
  }'

const res = await fetch(`https://trigglio.com/api/v1/chatbots/${chatbotId}/search`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tr_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'How do I cancel my subscription?',
    limit: 5,
    mode: 'hybrid',
    threshold: 0.4,
  }),
});
 
const { results, totalResults } = await res.json();
 
results.forEach(result => {
  console.log(`[${result.score}] ${result.sourceName}: ${result.content}`);
});

import requests
 
res = requests.post(
    f'https://trigglio.com/api/v1/chatbots/{chatbot_id}/search',
    headers={
        'Authorization': 'Bearer tr_live_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'query': 'How do I cancel my subscription?',
        'limit': 5,
        'mode': 'hybrid',
        'threshold': 0.4,
    }
)
 
data = res.json()
for result in data['results']:
    print(f"[{result['score']}] {result['sourceName']}: {result['content'][:100]}")

Response

{
  "status": "success",
  "results": [
    {
      "id": "chunk_abc123",
      "content": "To cancel your subscription, go to Settings > Billing > Cancel Plan. Cancellations take effect at the end of your current billing period.",
      "score": 0.892,
      "sourceId": "src_xyz789",
      "sourceName": "Subscription Policy",
      "metadata": {
        "section": "cancellation",
        "source": "policy"
      }
    },
    {
      "id": "chunk_def456",
      "content": "Refunds are available within 14 days of purchase for annual plans. Monthly plans are non-refundable.",
      "score": 0.754,
      "sourceId": "src_xyz789",
      "sourceName": "Subscription Policy",
      "metadata": {
        "section": "refunds",
        "source": "policy"
      }
    }
  ],
  "totalResults": 2,
  "query": "How do I cancel my subscription?",
  "mode": "hybrid",
  "threshold": 0.4
}

Tips

• Start with "vector" mode — it’s fast and works well for most queries
• Use "hybrid" for keyword-sensitive searches — when exact terms matter (product names, error codes)
• Use "smart" for production chatbots — maximum accuracy, slightly slower
• Lower the threshold to get more results (e.g., 0.2), raise it to get only highly relevant matches (e.g., 0.6)
• Process sources first — only sources with status "ready" are searchable

Error Codes