Content Model

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:

draft

Item is created but not yet published

queued

Item is queued for processing

processing

Media is being transcribed and indexed for search

ready

Processing complete, ready to be published

published

Item is live and searchable by users

unpublished

Item was published but is now hidden from search

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

Item → Collection (Required)

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

Series → Collection (Required)

Every series must belong to exactly one collection.

{
  "title": "Leadership Series",
  "collectionId": 1  // Required
}

Item → Speakers (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

Item → Series (Optional)

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

Getting Started

Core Concepts

Guides

Overview

Core Entities

Items

Collections

Series

Speakers

Content Hierarchy

Relationships Explained

Required Relationships

Optional Relationships

Working with the Content Model

Creating a Complete Item

Content Organization Best Practices

Plan Your Collections

Use Series Strategically

Consistent Speaker Names

Add Descriptive Metadata

URL Slugs

Next Steps

Media Management

Managing Content Guide

​Overview

​Core Entities

​Items

​Collections

​Series

​Speakers

​Content Hierarchy

​Relationships Explained

​Required Relationships

​Optional Relationships

​Working with the Content Model

​Creating a Complete Item

​Querying with Related Data

​Content Organization Best Practices

Plan Your Collections

Use Series Strategically

Consistent Speaker Names

Add Descriptive Metadata

​URL Slugs

​Next Steps

Media Management

Managing Content Guide

Overview

Core Entities

Items

Collections

Series

Speakers

Content Hierarchy

Relationships Explained

Required Relationships

Optional Relationships

Working with the Content Model

Creating a Complete Item

Querying with Related Data

Content Organization Best Practices

URL Slugs

Next Steps