Skip to main content

​
Overview

Haystack uses a hierarchical content model that helps you organize and categorize your media library. Understanding these relationships is key to effectively managing your content.

​
Core Entities

​
Items

Items are the fundamental unit of content in Haystack. An item typically represents a single piece of content like a sermon, talk, podcast episode, or video. 
{
  "id": 42,
  "title": "Leading with Humility",
  "subTitle": "Part 2 of Leadership Series",
  "description": "A deep dive into servant leadership...",
  "date": "2025-01-15",
  "status": "published",
  "collectionId": 1,
  "seriesId": 5,
  "urlSlug": "leading-with-humility"
}
Key Properties:
  • title - The main title of the content
  • date - Publication or recording date
  • status - Current state: draft, queued, processing, ready, published, unpublished, or error
  • collectionId - Required: which collection this belongs to
  • seriesId - Optional: which series this belongs to
Item Lifecycle:
1

draft

Item is created but not yet published
2

queued

Item is queued for processing
3

processing

Media is being transcribed and indexed for search
4

ready

Processing complete, ready to be published
5

published

Item is live and searchable by users
6

unpublished

Item was published but is now hidden from search
7

error

Processing failed - check error details

​
Collections

Collections are top-level organizational containers. They represent major categories of content and every item must belong to exactly one collection. 
{
  "id": 1,
  "name": "Sunday Sermons",
  "itemDescriptor": "sermon"
}
Use Cases:
  • Organizing by content type (Sermons, Podcasts, Conferences)
  • Separating by venue (Main Campus, Satellite Location)
  • Dividing by audience (Youth, Adults, Spanish)
Collections are required for all items. Plan your collection structure before importing content.

​
Series

Series group related items together in a sequence. Series are optional but highly recommended for organizing multi-part content. 
{
  "id": 5,
  "title": "Leadership Principles",
  "description": "A 4-week series on biblical leadership",
  "collectionId": 1,
  "published": true,
  "colorHex": "#4A90E2",
  "itemSortDirection": "DESC",
  "showItemOrderInSeries": true
}
Key Features:
  • Ordering: Control whether items display in ascending or descending order
  • Numbering: Optionally show “Part 1”, “Part 2” labels
  • Branding: Each series can have custom artwork and colors
  • Discovery: Users can find related content by browsing series

​
Speakers

Speakers represent the people who deliver your content. Items can have multiple speakers. 
{
  "id": 10,
  "name": "Pastor John Smith",
  "bio": "Senior Pastor since 2015...",
  "imageFilename": "john-smith-headshot.jpg"
}
Relationships:
  • Items must have at least one speaker
  • Items can have multiple speakers
  • Speakers can be associated with many items
  • Speaker filtering enables users to find all content by a specific person

​
Content Hierarchy

Here’s how these entities relate to each other: 
Customer
└── Collections (one or more)
    ├── Series (optional, multiple allowed)
    │   └── Items (optional, multiple allowed)
    └── Items (one or more)
        ├── Speakers (required, at least one)
        ├── Media Assets (optional, multiple allowed)
        ├── Scriptures (optional, multiple allowed)
        └── Artwork (optional, multiple allowed)

​
Relationships Explained

​
Required Relationships

Every item must belong to exactly one collection. This cannot be null.
// ✅ Valid - has collectionId
{
  "title": "My Sermon",
  "date": "2025-01-15",
  "collectionId": 1
}

// ❌ Invalid - missing collectionId
{
  "title": "My Sermon",
  "date": "2025-01-15"
}
Every series must belong to exactly one collection.
{
  "title": "Leadership Series",
  "collectionId": 1  // Required
}
Every item must have at least one speaker. Items can have multiple speakers.
// ✅ Valid - has at least one speaker
{
  "title": "My Sermon",
  "date": "2025-01-15",
  "collectionId": 1,
  "speakers": [{ "id": 10 }]
}

// ✅ Valid - multiple speakers
{
  "title": "Panel Discussion",
  "date": "2025-01-15",
  "collectionId": 1,
  "speakers": [{ "id": 10 }, { "id": 15 }]
}

// ❌ Invalid - no speakers
{
  "title": "My Sermon",
  "date": "2025-01-15",
  "collectionId": 1,
  "speakers": []
}

​
Optional Relationships

Items can optionally belong to a series, but it’s not required.
// Standalone item (no series)
{
  "title": "Easter Special",
  "collectionId": 1,
  "seriesId": null
}

// Part of a series
{
  "title": "Leadership Part 1",
  "collectionId": 1,
  "seriesId": 5
}

​
Working with the Content Model

​
Creating a Complete Item

Here’s a comprehensive example of creating an item with all relationships: 
const newItem = {
  // Basic info
  title: "Leading with Humility",
  subTitle: "Part 2 of Leadership Series",
  description: "A deep dive into servant leadership principles",
  shortDescription: "Learn to lead like Jesus",
  date: "2025-01-15",

  // Required relationships
  collectionId: 1,
  speakers: [
    { id: 10 }  // Pastor John
  ],

  // Optional relationships
  seriesId: 5,

  // Auto-publishing
  autoPublish: false  // Keep as draft, publish manually when ready
};

const response = await fetch(`${API_URL}/items/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(newItem)
});
Use the _expand query parameter to include related data: 
# Get item with all related data
curl "$API_URL/items/42?_expand=collection&_expand=series&_expand=speakers" \
  -H "Authorization: Bearer $API_TOKEN"
Response includes nested objects: 
{
  "item": {
    "id": 42,
    "title": "Leading with Humility",
    "collection": {
      "id": 1,
      "name": "Sermons"
    },
    "series": {
      "id": 5,
      "title": "Leadership Principles"
    },
    "speakers": [
      {
        "id": 10,
        "name": "Pastor John Smith"
      }
    ]
  }
}

​
Content Organization Best Practices

Plan Your Collections

Design your collection structure before importing content. Collections are the foundation of your organization.

Use Series Strategically

Group related content into series for better discovery and user engagement.

Consistent Speaker Names

Maintain consistent speaker naming to avoid duplicates (e.g., don’t create both “John Smith” and “Pastor John”).

Add Descriptive Metadata

Use descriptions and subtitles to provide context and improve searchability.

​
URL Slugs

Items and series can have custom URL slugs for user-friendly URLs: 
{
  "title": "Leading with Humility",
  "urlSlug": "leading-with-humility"
}
Slug Rules:
  • Lowercase letters, numbers, and hyphens only
  • Must be unique within your customer account
  • Auto-generated from title if not provided

​
Next Steps

Media Management

Learn how to attach media assets to your items

Managing Content Guide

Step-by-step guide to creating and organizing content