Skip to main content

​
Overview

Haystack provides powerful semantic search that goes beyond simple keyword matching. Users can search using natural language questions, and Haystack understands meaning and context to return the most relevant results.

​
Search API

No Authentication Required: The search endpoint uses your church-specific Search API URL and does not require authentication. Never include your API token when calling search from public-facing applications.
// Your church-specific Search API URL
const SEARCH_URL = 'https://your-church-name.thehaystack.ai/api';
const query = "how to pray";

const response = await fetch(
  `${SEARCH_URL}/haystack/search?q=${encodeURIComponent(query)}`,
  {
    headers: {
      'Content-Type': 'application/json'
    }
  }
);

const results = await response.json();
Find your Search API Base URL in the Haystack Dashboard under Developer → API.
Advanced Feature: Add ?stream=true to receive a Server-Sent Events stream with an AI-generated overview of search results. Perfect for creating rich search experiences with AI summaries. Learn more

​
Search Response

{
  "query": "how to pray",
  "queryAnalyticsId": "abc123",
  "items": [
    {
      "item": {
        "id": 42,
        "title": "The Power of Prayer",
        "date": "2025-01-15"
      },
      "score": 0.89,
      "highlights": [
        {
          "transcript": "So let me share three practical ways to deepen your prayer life...",
          "startMs": 145000,
          "endMs": 152000,
          "thumbnailUrl": "https://image.mux.com/.../thumbnail.jpg?time=145"
        }
      ]
    }
  ],
  "scriptures": [
    {
      "book": "matthew",
      "bookName": "Matthew",
      "chapter": 6,
      "numItems": 12
    }
  ],
  "series": [
    {
      "series": {
        "id": 5,
        "title": "Spiritual Disciplines"
      },
      "numItems": 4,
      "linkedItemUrlSlug": "power-of-prayer"
    }
  ]
}

​
Search Result Types

Haystack returns three types of results:

​
Item Results

Individual content items with highlights showing relevant sections. 
{
  "item": { /* item details */ },
  "score": 0.85,
  "highlights": [
    {
      "transcript": "exact text from transcript",
      "startMs": 120000,
      "endMs": 127000,
      "score": 0.89
    }
  ]
}
Key Fields:
  • score - Overall relevance (0-1, higher is better)
  • highlights - Most relevant segments with timestamps
  • thumbnailUrl - Visual preview of the segment (only available when using Haystack custom player; use item artwork for YouTube/Vimeo)

​
Scripture Results

Bible passages related to the search query. 
{
  "book": "matthew",
  "bookName": "Matthew",
  "chapter": 6,
  "numItems": 12
}
Haystack automatically:
  • Detects biblical references in queries (“Matthew 6”)
  • Finds thematic scripture connections (“forgiveness” → Matthew 6:14-15)
  • Shows how many items reference each passage

​
Series Results

Entire series related to the query. 
{
  "series": {
    "id": 5,
    "title": "Spiritual Disciplines",
    "description": "A 4-week series on prayer, fasting, and worship"
  },
  "numItems": 4,
  "linkedItemUrlSlug": "power-of-prayer"
}
Useful when users want comprehensive content on a topic.

​
Search Features

​
Semantic Understanding

Haystack understands meaning, not just keywords:
QueryMatches
”how to pray""prayer life”, “talking to God”, “spending time with the Lord"
"dealing with anxiety""worry”, “fear”, “stress”, “peace"
"relationships""marriage”, “friendship”, “dating”, “family”

​
Highlights

Each result includes 1-3 highlights showing the most relevant sections: 
{
  "highlights": [
    {
      "transcript": "The actual words spoken in this segment...",
      "startMs": 145000,    // 2:25 into the video
      "endMs": 152000,      // 2:32
      "score": 0.89,
      "thumbnailUrl": "https://..."
    }
  ]
}
Use highlights to:
  • Show preview text in search results
  • Enable “jump to moment” functionality
  • Display thumbnail previews

​
Scripture Detection

Haystack recognizes Bible references in multiple formats:
  • Book and chapter: “John 3”
  • Full reference: “John 3:16”
  • Natural language: “when Jesus talked to Nicodemus”
  • Alternative names: “1st John”, “First John”, “1 John”

​
Best Practices

Track All Searches

Log every search query to understand user intent and identify gaps in your content

Show Visual Previews

Use thumbnail URLs from highlights to give users visual context

Implement Jump to Moment

Let users jump directly to relevant timestamps instead of watching from the beginning

Monitor Zero Results

Track searches that return no results to identify missing content topics

​
Next Steps

API Reference

Full search API documentation