Authentication

Overview

The Haystack API uses Bearer token authentication to secure API requests. Most API endpoints require a valid authentication token in the Authorization header.

Search Endpoint Exception: The Search endpoint does NOT require authentication. It is designed to be called from public-facing websites and applications. Never include your API token when calling the search endpoint, as this would expose your credentials to end users.

Two Types of API Access

Haystack provides two separate APIs for different use cases:

Search API (Public, No Authentication)

Purpose: Search your content library from anywhere, including public websites
Authentication: None required
Base URL: https://{your-church-shortname}.thehaystack.ai/api
Use from: Frontend JavaScript, mobile apps, any public-facing application

Private API (Authenticated)

Purpose: Manage your library, access analytics, update settings
Authentication: API key required (Bearer token)
Base URL: https://api.thehaystack.ai/v2/haystack
Use from: Backend servers only (never from frontend code)

Getting Your Search API Base URL

The Search API base URL is specific to your organization:

Log in to your Haystack Dashboard
Navigate to Developer → API
Find your Search API Base URL in the Search API section
Click Copy to copy the URL to your clipboard

Your Search API base URL will look like:

https://your-church-name.thehaystack.ai/api

The Search API does not require authentication. You can use it directly from frontend JavaScript without exposing any credentials.

Getting Your Private API Token

To create a Private API token for authenticated requests:

Log in to your Haystack Dashboard
Navigate to Developer → API
In the Private API section, click New key
Enter a descriptive name for your key (e.g., “Production Server”)
Choose whether to enable Admin privileges (only if needed for user/billing management)
Click Submit
Important: Copy your API key immediately - you won’t be able to see it again!

Keep Your API Key Private: This key provides access to your Haystack account. Never share it, expose it in frontend code, or commit it to version control. Store it securely using environment variables or a secrets manager.

Making Authenticated Requests (Private API)

For Private API endpoints, include your API token in the Authorization header using the Bearer authentication scheme:

Authorization: Bearer YOUR_API_TOKEN

Example Private API Request

curl https://api.thehaystack.ai/v2/haystack/items \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

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

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

const data = await response.json();

import os
import requests

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

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

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

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

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

const data = await response.json();

Example Search API Request (No Authentication)

curl "https://your-church-name.thehaystack.ai/api/haystack/search?q=prayer"

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

const response = await fetch(
  `${SEARCH_API_URL}/haystack/search?q=${encodeURIComponent('prayer')}`,
  {
    headers: {
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

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

params = {'q': 'prayer'}
response = requests.get(f'{SEARCH_API_URL}/haystack/search', params=params)
data = response.json()

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

const response = await fetch(
  `${SEARCH_API_URL}/haystack/search?q=${encodeURIComponent('prayer')}`,
  {
    headers: {
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

Which API Should I Use?

Choose the appropriate API based on where your code runs:

Scenario	API to Use	Base URL	Authentication
Search from website	Search API	`https://{your-shortname}.thehaystack.ai/api`	None
Search from mobile app	Search API	`https://{your-shortname}.thehaystack.ai/api`	None
Manage content from backend	Private API	`https://api.thehaystack.ai/v2/haystack`	API Key required
Upload media from backend	Private API	`https://api.thehaystack.ai/v2/haystack`	API Key required
Access analytics from backend	Private API	`https://api.thehaystack.ai/v2/haystack`	API Key required

Never use Private API keys in frontend code. API keys should only be used from backend servers where they can be kept secure. For public-facing search functionality, use the Search API which requires no authentication.

Authentication Errors

The API returns specific error responses for authentication issues:

401 Unauthorized

Returned when your API token is missing, invalid, or expired.

{
  "result": "error",
  "error": {
    "type": "Unauthorized",
    "message": "Invalid or missing authentication token"
  }
}

Resolution: Verify your token is correct and included in the Authorization header.

403 Forbidden

Returned when your token is valid but you don’t have permission to access the requested resource.

{
  "result": "error",
  "error": {
    "type": "Forbidden",
    "message": "Insufficient permissions to access this resource"
  }
}

Resolution: Ensure your API token has the necessary permissions for the resource you’re trying to access.

Next Steps

Now that you understand authentication, you’re ready to make your first API call:

Quickstart Guide

Follow our quickstart tutorial to make your first authenticated API request

Getting Started

Core Concepts

Guides

Overview

Two Types of API Access

Search API (Public, No Authentication)

Private API (Authenticated)

Getting Your Search API Base URL

Getting Your Private API Token

Making Authenticated Requests (Private API)

Example Private API Request

Example Search API Request (No Authentication)

Which API Should I Use?

Authentication Errors

401 Unauthorized

403 Forbidden

Next Steps

Quickstart Guide

​Overview

​Two Types of API Access

​Search API (Public, No Authentication)

​Private API (Authenticated)

​Getting Your Search API Base URL

​Getting Your Private API Token

​Making Authenticated Requests (Private API)

​Example Private API Request

​Example Search API Request (No Authentication)

​Which API Should I Use?

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Next Steps

Quickstart Guide

Overview

Two Types of API Access

Search API (Public, No Authentication)

Private API (Authenticated)

Getting Your Search API Base URL

Getting Your Private API Token

Making Authenticated Requests (Private API)

Example Private API Request

Example Search API Request (No Authentication)

Which API Should I Use?

Authentication Errors

401 Unauthorized

403 Forbidden

Next Steps