Skip to main content
GET
/
search
Search content
curl --request GET \
  --url https://{churchShortname}.thehaystack.ai/api/haystack/search
{
  "query": "<string>",
  "queryAnalyticsId": "<string>",
  "items": [
    {
      "item": {
        "id": 123,
        "title": "The Power of Prayer",
        "subTitle": "<string>",
        "description": "<string>",
        "shortDescription": "<string>",
        "date": "2025-01-15",
        "collectionId": 123,
        "seriesId": 123,
        "orderInSeries": 123,
        "urlSlug": "<string>",
        "durationSecs": 123,
        "status": "draft",
        "wizardStep": "basicDetails",
        "publishedDate": "2023-11-07T05:31:56Z",
        "autoPublish": true,
        "squareImgUrl": "<string>",
        "wideImgUrl": "<string>",
        "ultraWideImgUrl": "<string>",
        "verticalImgUrl": "<string>",
        "entryDate": "2023-11-07T05:31:56Z",
        "collection": {
          "id": 1,
          "name": "Sunday Sermons",
          "itemDescriptor": "sermon",
          "contentFormat": "sermon",
          "fullService": false,
          "variantTypes": [
            {
              "id": 123,
              "name": "Sermon Video",
              "contentType": "video",
              "indexable": true,
              "displayOrder": 123,
              "collectionId": 123
            }
          ]
        },
        "series": {
          "id": 123,
          "title": "The Gospel of John",
          "subTitle": "<string>",
          "collectionId": 123,
          "description": "<string>",
          "shortDescription": "<string>",
          "sortOrder": 123,
          "itemSortDirection": "DESC",
          "showItemOrderInSeries": true,
          "urlSlug": "<string>",
          "colorHex": "#FF5733",
          "squareImgUrl": "<string>",
          "wideImgUrl": "<string>",
          "ultraWideImgUrl": "<string>",
          "published": true,
          "verticalImgUrl": "<string>",
          "squareImgMetadata": {},
          "wideImgMetadata": {},
          "ultraWideImgMetadata": {},
          "verticalImgMetadata": {},
          "items": "<array>",
          "collection": {
            "id": 1,
            "name": "Sunday Sermons",
            "itemDescriptor": "sermon",
            "contentFormat": "sermon",
            "fullService": false,
            "variantTypes": [
              {
                "id": 123,
                "name": "Sermon Video",
                "contentType": "video",
                "indexable": true,
                "displayOrder": 123,
                "collectionId": 123
              }
            ]
          }
        },
        "speakers": [
          {
            "id": 123,
            "name": "Pastor John Smith",
            "bio": "<string>",
            "imageUrl": "<string>",
            "imageFilename": "<string>",
            "itemCount": 123
          }
        ],
        "scriptures": [
          {
            "id": 123,
            "itemId": 123,
            "book": "<string>",
            "bookName": "Matthew",
            "chapter": 123,
            "verseStart": 123,
            "verseEnd": 123,
            "keyVerse": true,
            "suggested": true,
            "accepted": true,
            "displayOrder": 123,
            "citation": "Matthew 5:1-12",
            "hidden": true
          }
        ],
        "mediaAssets": [
          {
            "id": 123,
            "itemId": 123,
            "item": "<unknown>",
            "contentType": "audio",
            "mimeType": "<string>",
            "variantTypeId": 123,
            "variantType": {
              "id": 123,
              "name": "Sermon Video",
              "contentType": "video",
              "indexable": true,
              "displayOrder": 123,
              "collectionId": 123
            },
            "fileSizeBytes": 123,
            "durationSecs": 123,
            "bitrate": 123,
            "videoWidth": 123,
            "videoHeight": 123,
            "filename": "<string>",
            "originalFilename": "<string>",
            "externalPlatform": "youtube",
            "externalPlatformId": "<string>",
            "muxAssetId": "<string>",
            "muxPlaybackId": "<string>",
            "status": "created",
            "url": "<string>",
            "downloadUrl": "<string>",
            "chapters": [
              {
                "id": 123,
                "itemId": 123,
                "mediaAssetId": 123,
                "title": "Introduction",
                "startMs": 123,
                "suggested": true,
                "accepted": true,
                "hidden": true
              }
            ],
            "entryDate": "2023-11-07T05:31:56Z"
          }
        ],
        "resources": [
          {
            "id": 123,
            "itemId": 123,
            "title": "<string>",
            "subTitle": "<string>",
            "description": "<string>",
            "resourceTypeId": 123,
            "displayOrder": 123,
            "contentType": "file",
            "fileMimeType": "<string>",
            "fileSizeBytes": 123,
            "externalPlatform": "youtube",
            "externalPlatformId": "<string>",
            "thumbnailImgUrl": "<string>",
            "url": "<string>",
            "resourceType": {
              "id": 123,
              "name": "<string>"
            },
            "linkTarget": "<string>"
          }
        ],
        "suggestedDescription": "<string>",
        "suggestedShortDescription": "<string>",
        "errorMessage": "<string>",
        "indexedMediaAssetId": 123,
        "autoAcceptScriptures": true,
        "autoAcceptMediaChapters": true,
        "transcriptUrl": "<string>",
        "topics": [
          {
            "id": 123,
            "name": "<string>",
            "itemCount": 123
          }
        ],
        "squareImgMetadata": {},
        "wideImgMetadata": {},
        "ultraWideImgMetadata": {},
        "verticalImgMetadata": {}
      },
      "score": 123,
      "highlights": [
        {
          "transcript": "<string>",
          "startMs": 123,
          "endMs": 123,
          "score": 123,
          "thumbnailUrl": "<string>"
        }
      ]
    }
  ],
  "scriptures": [
    {
      "book": "matthew",
      "bookName": "Matthew",
      "chapter": 123,
      "numItems": 123
    }
  ],
  "series": [
    {
      "series": {
        "id": 123,
        "title": "The Gospel of John",
        "subTitle": "<string>",
        "collectionId": 123,
        "description": "<string>",
        "shortDescription": "<string>",
        "sortOrder": 123,
        "itemSortDirection": "DESC",
        "showItemOrderInSeries": true,
        "urlSlug": "<string>",
        "colorHex": "#FF5733",
        "squareImgUrl": "<string>",
        "wideImgUrl": "<string>",
        "ultraWideImgUrl": "<string>",
        "published": true,
        "verticalImgUrl": "<string>",
        "squareImgMetadata": {},
        "wideImgMetadata": {},
        "ultraWideImgMetadata": {},
        "verticalImgMetadata": {},
        "items": "<array>",
        "collection": {
          "id": 1,
          "name": "Sunday Sermons",
          "itemDescriptor": "sermon",
          "contentFormat": "sermon",
          "fullService": false,
          "variantTypes": [
            {
              "id": 123,
              "name": "Sermon Video",
              "contentType": "video",
              "indexable": true,
              "displayOrder": 123,
              "collectionId": 123
            }
          ]
        }
      },
      "numItems": 123,
      "linkedItemUrlSlug": "<string>"
    }
  ],
  "itemDescriptor": "sermon"
}

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.

No Authentication Required: This endpoint does NOT require authentication. Never include your API token when calling this endpoint, especially from client-side JavaScript, as this would expose your credentials to all users.
Using “Try It Out”: This endpoint requires a church-specific base URL. To test this endpoint:
  1. Click the server dropdown and select “Your church-specific Search API”
  2. Replace {churchShortname} with your actual church shortname
  3. Find your shortname in the Haystack Dashboard under Developer → API
Example: If your Search API URL is https://gracechurch.thehaystack.ai/api, your shortname is gracechurch.

​
Response Format

The search endpoint supports two response formats:

​
Standard JSON Response (Default)

Fast, simple response with search results only. Best for most use cases. 
const SEARCH_URL = 'https://your-church-name.thehaystack.ai/api';

const response = await fetch(
  `${SEARCH_URL}/haystack/search?q=${encodeURIComponent('prayer')}`
);

const data = await response.json();
// Returns: { query, queryAnalyticsId, items, scriptures, series }
console.log('Found', data.items.length, 'items');

​
Streaming Response with AI Overview (Advanced)

For an AI-generated overview of results, add ?stream=true to receive a Server-Sent Events stream. This feature is best suited for advanced integrations that need real-time AI summaries.
Event Types:
  • results: Search results (same structure as JSON response)
  • overview: Chunks of AI-generated summary as they’re generated
  • complete: Stream finished successfully
  • error: An error occurred
Example Implementations:
const SEARCH_URL = 'https://your-church-name.thehaystack.ai/api';

const eventSource = new EventSource(
  `${SEARCH_URL}/haystack/search?q=prayer&stream=true`
);

let overviewText = '';

eventSource.addEventListener('results', (event) => {
  const message = JSON.parse(event.data);
  console.log('Results:', message.data);
});

eventSource.addEventListener('overview', (event) => {
  const message = JSON.parse(event.data);
  overviewText += message.data.overview;
  console.log('Overview chunk:', message.data.overview);
});

eventSource.addEventListener('complete', () => {
  console.log('Complete overview:', overviewText);
  eventSource.close();
});

eventSource.addEventListener('error', (event) => {
  console.error('Error:', JSON.parse(event.data).error);
  eventSource.close();
});
Popular SSE Libraries:
  • Python: sseclient-py, aiohttp-sse-client
  • PHP: mpociot/php-sse-client, artax/sse
  • Ruby: celluloid-eventsource, sse-client
  • Node.js: eventsource, built-in fetch with stream handling
  • Go: r3labs/sse, standard http package

Query Parameters

​
q
string
required

Natural-language search query

​
surface
enum<string>
required
Available options:
embed,
connect,
console
​
embedToken
string

Required when surface=embed

​
collectionId
integer

Scope search to a single collection

​
stream
boolean

When true, responds with Server-Sent Events streaming the AI overview as it is generated

​
overviewFormat
string

Format hint for the AI overview

Response

Search results. Returns JSON by default, or Server-Sent Events stream when stream=true.

​
query
string
​
queryAnalyticsId
string
​
items
object[]
​
scriptures
object[]
​
series
object[]
​
itemDescriptor
enum<string>

Descriptor inherited from the searched collection

Available options:
sermon,
message,
teaching,
episode