> ## Documentation Index
> Fetch the complete documentation index at: https://developer.thehaystack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Content Model

> Understanding how content is organized in Haystack

## 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.

```json theme={null}
{
  "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:**

<Steps>
  <Step title="draft">
    Item is created but not yet published
  </Step>

  <Step title="queued">
    Item is queued for processing
  </Step>

  <Step title="processing">
    Media is being transcribed and indexed for search
  </Step>

  <Step title="ready">
    Processing complete, ready to be published
  </Step>

  <Step title="published">
    Item is live and searchable by users
  </Step>

  <Step title="unpublished">
    Item was published but is now hidden from search
  </Step>

  <Step title="error">
    Processing failed - check error details
  </Step>
</Steps>

### Collections

**Collections** are top-level organizational containers. They represent major categories of content and every item must belong to exactly one collection.

```json theme={null}
{
  "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)

<Note>
  Collections are required for all items. Plan your collection structure before importing content.
</Note>

### Series

**Series** group related items together in a sequence. Series are optional but highly recommended for organizing multi-part content.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Item → Collection (Required)">
    Every item must belong to exactly one collection. This cannot be null.

    ```javascript theme={null}
    // ✅ Valid - has collectionId
    {
      "title": "My Sermon",
      "date": "2025-01-15",
      "collectionId": 1
    }

    // ❌ Invalid - missing collectionId
    {
      "title": "My Sermon",
      "date": "2025-01-15"
    }
    ```
  </Accordion>

  <Accordion title="Series → Collection (Required)">
    Every series must belong to exactly one collection.

    ```javascript theme={null}
    {
      "title": "Leadership Series",
      "collectionId": 1  // Required
    }
    ```
  </Accordion>

  <Accordion title="Item → Speakers (Required)">
    Every item must have at least one speaker. Items can have multiple speakers.

    ```javascript theme={null}
    // ✅ 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": []
    }
    ```
  </Accordion>
</AccordionGroup>

### Optional Relationships

<AccordionGroup>
  <Accordion title="Item → Series (Optional)">
    Items can optionally belong to a series, but it's not required.

    ```javascript theme={null}
    // Standalone item (no series)
    {
      "title": "Easter Special",
      "collectionId": 1,
      "seriesId": null
    }

    // Part of a series
    {
      "title": "Leadership Part 1",
      "collectionId": 1,
      "seriesId": 5
    }
    ```
  </Accordion>
</AccordionGroup>

## Working with the Content Model

### Creating a Complete Item

Here's a comprehensive example of creating an item with all relationships:

```javascript theme={null}
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)
});
```

### Querying with Related Data

Use the `_expand` query parameter to include related data:

```bash theme={null}
# 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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Plan Your Collections" icon="sitemap">
    Design your collection structure before importing content. Collections are the foundation of your organization.
  </Card>

  <Card title="Use Series Strategically" icon="layer-group">
    Group related content into series for better discovery and user engagement.
  </Card>

  <Card title="Consistent Speaker Names" icon="user">
    Maintain consistent speaker naming to avoid duplicates (e.g., don't create both "John Smith" and "Pastor John").
  </Card>

  <Card title="Add Descriptive Metadata" icon="file-lines">
    Use descriptions and subtitles to provide context and improve searchability.
  </Card>
</CardGroup>

## URL Slugs

Items and series can have custom URL slugs for user-friendly URLs:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Media Management" icon="video" href="/concepts/media-management">
    Learn how to attach media assets to your items
  </Card>

  <Card title="Managing Content Guide" icon="book" href="/guides/managing-content">
    Step-by-step guide to creating and organizing content
  </Card>
</CardGroup>