Skip to main content
GET
/
search
Search content
curl --request GET \
  --url https://api.thehaystack.ai/v2/bevly/search \
  --header 'Authorization: Bearer <token>'
{
  "query": "<string>",
  "queryAnalyticsId": "<string>",
  "items": [
    {
      "item": {
        "id": 123,
        "title": "The Power of Prayer",
        "subTitle": "<string>",
        "description": "<string>",
        "date": "2025-01-15",
        "collectionId": 123,
        "seriesId": 123,
        "status": "draft",
        "publishedDate": "2023-11-07T05:31:56Z",
        "autoPublish": true,
        "urlSlug": "<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

Authorizations

​
Authorization
string
header
required

Enter your API token from the Haystack dashboard

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.

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