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"
        },
        "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
        },
        "speakers": [
          {
            "id": 123,
            "name": "Pastor John Smith",
            "bio": "<string>",
            "imageUrl": "<string>"
          }
        ],
        "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,
            "contentType": "video",
            "status": "created",
            "duration": 123,
            "muxAssetId": "<string>",
            "muxPlaybackId": "<string>",
            "variantTypeId": 123,
            "variantType": {
              "id": 123,
              "name": "Sermon Video",
              "contentType": "video",
              "indexable": true,
              "displayOrder": 123,
              "collectionId": 123
            }
          }
        ],
        "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>"
          }
        ]
      },
      "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
      },
      "numItems": 123,
      "linkedItemUrlSlug": "<string>"
    }
  ]
}
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

Search query

Example:

"how to pray"

​
stream
boolean
default:false

Set to 'true' to receive a streaming response with AI-generated overview (Server-Sent Events). Default is 'false' for standard JSON response.

​
format
enum<string>
default:markdown

Format for the AI-generated overview. Use 'markdown' for rich formatting or 'text' for plain text.

Available options:
markdown,
text

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[]