Quick Start

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.

Get Your API Credentials

Haystack provides two APIs. Get the credentials you need from the Haystack Dashboard:For the Private API (content management, analytics):

Navigate to Developer → API
In the Private API section, click New key
Enter a name (e.g., “Development Server”) and click Submit
Copy and save your API key securely (you won’t see it again!)

For the Search API (public search, no authentication):

Navigate to Developer → API
In the Search API section, find your Search API Base URL
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.

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/haystack"

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

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

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"

const API_URL = 'https://api.thehaystack.ai/v2/haystack';
const API_TOKEN = process.env.HAYSTACK_API_TOKEN;

async function getCollections() {
  const response = await fetch(`${API_URL}/collections`, {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log('Collections:', data.collections);
  return data;
}

getCollections();

import os
import requests

API_URL = 'https://api.thehaystack.ai/v2/haystack'
API_TOKEN = os.getenv('HAYSTACK_API_TOKEN')

def get_collections():
    headers = {
        'Authorization': f'Bearer {API_TOKEN}',
        'Content-Type': 'application/json'
    }

    response = requests.get(f'{API_URL}/collections', headers=headers)
    data = response.json()

    print('Collections:', data['collections'])
    return data

get_collections()

const API_URL = 'https://api.thehaystack.ai/v2/haystack';
const API_TOKEN = process.env.HAYSTACK_API_TOKEN;

interface Collection {
  id: number;
  name: string;
  customerId: number;
}

interface CollectionsResponse {
  collections: Collection[];
  total: number;
  page: number;
  pageSize: number;
}

async function getCollections(): Promise<CollectionsResponse> {
  const response = await fetch(`${API_URL}/collections`, {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log('Collections:', data.collections);
  return data;
}

getCollections();

Expected Response:

{
  "collections": [
    {
      "id": 1,
      "name": "Sermons",
      "itemDescriptor": "sermon"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

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"

const SEARCH_URL = 'https://your-church-name.thehaystack.ai/api';

async function searchContent(query) {
  const response = await fetch(
    `${SEARCH_URL}/haystack/search?q=${encodeURIComponent(query)}`,
    {
      headers: {
        'Content-Type': 'application/json'
      }
    }
  );

  const data = await response.json();
  console.log('Search results:', data.items);
  return data;
}

searchContent('leadership');

import requests

SEARCH_URL = 'https://your-church-name.thehaystack.ai/api'

def search_content(query):
    params = {'q': query}

    response = requests.get(
        f'{SEARCH_URL}/haystack/search',
        params=params
    )

    data = response.json()
    print('Search results:', data['items'])
    return data

search_content('leadership')

const SEARCH_URL = 'https://your-church-name.thehaystack.ai/api';

interface SearchResult {
  item: {
    id: number;
    title: string;
    description: string;
  };
  score: number;
  highlights: Array<{
    transcript: string;
    startMs: number;
    endMs: number;
  }>;
}

interface SearchResponse {
  query: string;
  queryAnalyticsId: string;
  items: SearchResult[];
  scriptures: any[];
  series: any[];
}

async function searchContent(query: string): Promise<SearchResponse> {
  const response = await fetch(
    `${SEARCH_URL}/haystack/search?q=${encodeURIComponent(query)}`,
    {
      headers: {
        'Content-Type': 'application/json'
      }
    }
  );

  const data = await response.json();
  console.log('Search results:', data.items);
  return data;
}

searchContent('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": []
}

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"
  }'

async function createItem() {
  const response = await fetch(`${API_URL}/items/create`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Getting Started with Haystack',
      date: '2025-01-15',
      collectionId: 1,
      description: 'An introduction to using Haystack API'
    })
  });

  const data = await response.json();
  console.log('Created item:', data.item);
  return data;
}

createItem();

def create_item():
    headers = {
        'Authorization': f'Bearer {API_TOKEN}',
        'Content-Type': 'application/json'
    }

    payload = {
        'title': 'Getting Started with Haystack',
        'date': '2025-01-15',
        'collectionId': 1,
        'description': 'An introduction to using Haystack API'
    }

    response = requests.post(
        f'{API_URL}/items/create',
        headers=headers,
        json=payload
    )

    data = response.json()
    print('Created item:', data['item'])
    return data

create_item()

interface CreateItemPayload {
  title: string;
  date: string;
  collectionId: number;
  description?: string;
  subTitle?: string;
}

async function createItem(itemData: CreateItemPayload) {
  const response = await fetch(`${API_URL}/items/create`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(itemData)
  });

  const data = await response.json();
  console.log('Created item:', data.item);
  return data;
}

createItem({
  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

Getting Started

Core Concepts

Guides

Overview

Error Handling

Next Steps

Content Model

Media Management

Search & Discovery

API Reference

​Overview

​Error Handling

​Next Steps

Content Model

Media Management

Search & Discovery

API Reference

Overview

Error Handling

Next Steps