Skip to main content

​
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/bevly
  • 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:
  1. Log in to your Haystack Dashboard
  2. Navigate to Developer → API
  3. Find your Search API Base URL in the Search API section
  4. 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:
  1. Log in to your Haystack Dashboard
  2. Navigate to Developer → API
  3. In the Private API section, click New key
  4. Enter a descriptive name for your key (e.g., “Production Server”)
  5. Choose whether to enable Admin privileges (only if needed for user/billing management)
  6. Click Submit
  7. 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/bevly/items \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

​
Example Search API Request (No Authentication)

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

​
Which API Should I Use?

Choose the appropriate API based on where your code runs:
ScenarioAPI to UseBase URLAuthentication
Search from websiteSearch APIhttps://{your-shortname}.thehaystack.ai/apiNone
Search from mobile appSearch APIhttps://{your-shortname}.thehaystack.ai/apiNone
Manage content from backendPrivate APIhttps://api.thehaystack.ai/v2/bevlyAPI Key required
Upload media from backendPrivate APIhttps://api.thehaystack.ai/v2/bevlyAPI Key required
Access analytics from backendPrivate APIhttps://api.thehaystack.ai/v2/bevlyAPI 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