Skip to main content

​
Overview

This guide will walk you through making your first API calls to Haystack. You’ll learn how to authenticate, retrieve content, and perform a search.
1

Get Your API Credentials

Haystack provides two APIs. Get the credentials you need from the Haystack Dashboard:For the Private API (content management, analytics):
  1. Navigate to Developer → API
  2. In the Private API section, click New key
  3. Enter a name (e.g., “Development Server”) and click Submit
  4. Copy and save your API key securely (you won’t see it again!)
For the Search API (public search, no authentication):
  1. Navigate to Developer → API
  2. In the Search API section, find your Search API Base URL
  3. Click Copy to copy your church-specific URL
Keep your Private API key secure. Never use it in frontend code or commit it to version control.
2

Set Up Your Environment

Store your credentials as environment variables:
# Private API (for backend use only)
export HAYSTACK_API_TOKEN="sk_..."
export HAYSTACK_API_URL="https://api.thehaystack.ai/v2/bevly"

# Search API (for frontend/public use)
export HAYSTACK_SEARCH_URL="https://your-church-name.thehaystack.ai/api"
Or create a .env file:
.env
# Private API (backend only)
HAYSTACK_API_TOKEN=sk_...
HAYSTACK_API_URL=https://api.thehaystack.ai/v2/bevly

# Search API (frontend safe)
HAYSTACK_SEARCH_URL=https://your-church-name.thehaystack.ai/api
3

Make Your First Request

Let’s retrieve your collections to verify authentication is working:
curl "$HAYSTACK_API_URL/collections" \
  -H "Authorization: Bearer $HAYSTACK_API_TOKEN" \
  -H "Content-Type: application/json"
Expected Response:
{
  "collections": [
    {
      "id": 1,
      "name": "Sermons",
      "itemDescriptor": "sermon"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}
4

Search Your Content

Now let’s perform a search query to find content:
No Authentication Required: The search endpoint uses your church-specific Search API URL and does not require authentication. It’s safe to call from public websites.
curl "$HAYSTACK_SEARCH_URL/haystack/search?q=leadership"
Want AI-generated search overviews? Add &stream=true to receive a streaming response with an AI summary of results. See the Search endpoint documentation for details.
Expected Response:
{
  "query": "leadership",
  "queryAnalyticsId": "abc123",
  "items": [
    {
      "item": {
        "id": 42,
        "title": "Servant Leadership",
        "description": "A message about leading with humility"
      },
      "score": 0.89,
      "highlights": [
        {
          "transcript": "Great leaders understand that leadership is about serving others...",
          "startMs": 45000,
          "endMs": 52000
        }
      ]
    }
  ],
  "scriptures": [],
  "series": []
}
5

Create Content

Let’s create a new item in your library:
curl -X POST "$HAYSTACK_API_URL/items/create" \
  -H "Authorization: Bearer $HAYSTACK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with Haystack",
    "date": "2025-01-15",
    "collectionId": 1,
    "description": "An introduction to using Haystack API"
  }'
Expected Response:
{
  "item": {
    "id": 100,
    "title": "Getting Started with Haystack",
    "date": "2025-01-15",
    "collectionId": 1,
    "description": "An introduction to using Haystack API",
    "status": "draft"
  }
}

​
Error Handling

Always check for errors in API responses. The API uses standard HTTP status codes: 
async function makeApiRequest(url, options) {
  const response = await fetch(url, options);

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error.message}`);
  }

  return response.json();
}
Common HTTP status codes:
  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid or missing token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 500 - Internal Server Error

​
Next Steps

Congratulations! You’ve made your first API calls to Haystack. Here’s what to explore next:

Content Model

Learn about items, collections, series, and how they relate

Media Management

Upload and manage video and audio files

Search & Discovery

Deep dive into semantic search capabilities

API Reference

Explore the complete API documentation