> ## Documentation Index
> Fetch the complete documentation index at: https://developer.thehaystack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search & Discovery

> How Haystack's semantic search works

## 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

### Basic Search

<Note>
  **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.
</Note>

```javascript theme={null}
// 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](https://app.thehaystack.ai) under **Developer** → **API**.

<Tip>
  **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](/api-reference/endpoints/search#streaming-response-with-ai-overview-advanced)
</Tip>

### Search Response

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

| Query                  | Matches                                                        |
| ---------------------- | -------------------------------------------------------------- |
| "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Track All Searches" icon="chart-line">
    Log every search query to understand user intent and identify gaps in your content
  </Card>

  <Card title="Show Visual Previews" icon="image">
    Use thumbnail URLs from highlights to give users visual context
  </Card>

  <Card title="Implement Jump to Moment" icon="clock">
    Let users jump directly to relevant timestamps instead of watching from the beginning
  </Card>

  <Card title="Monitor Zero Results" icon="magnifying-glass-minus">
    Track searches that return no results to identify missing content topics
  </Card>
</CardGroup>

## Next Steps

<Card title="API Reference" icon="book" href="/api-reference/introduction">
  Full search API documentation
</Card>