---
title: "Episode (Publishing)"
description: "The Episode resource in Planning Center Publishing: how to reach it, its attributes, and what you can query and write."
---

> Documentation Index
> Fetch the complete documentation index at: https://planningcenterkit.mackenly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Episode (Publishing)

| Property | Value |
| --- | --- |
| Product | [Publishing](/reference/publishing/) (`pco.publishing`, API version `2024-03-25`) |
| Resource type | `Episode` |
| TypeScript | `Publishing.Episode`, attributes `Publishing.EpisodeAttributes`, schema `Publishing.EpisodeSchema` |
| Planning Center path | `/publishing/v2/episodes` |
| Planning Center docs | [Episode](https://api.planningcenteronline.com/docs/apps/publishing/versions/2024-03-25/vertices/episode) |

## How to reach it

| Client path | Returns | Filters | Create |
| --- | --- | --- | --- |
| `pco.publishing.episodes` | Collection | `connected_to_services`, `not_connected_to_services`, `not_published_live`, `published_live`, `published_on_church_center` | Yes |
| `pco.publishing.channels.id(channelId).current_episode` | Collection |  | No |
| `pco.publishing.channels.id(channelId).episodes` | Collection | `connected_to_services`, `not_connected_to_services`, `not_published`, `published`, `published_to_library` | No |

From a collection, `.id(episodeId)` addresses one Episode: `pco.publishing.episodes.id(episodeId)`. Collections support [`where`, `include`, `order`, and pagination](/guides/querying/); single resources have `get()`.

## Attributes

On `Publishing.EpisodeAttributes`. Every resource also has `id` and `type` (`'Episode'`) next to its attributes.

| Name | Type | Description |
| --- | --- | --- |
| `art` | `Record<string, unknown> \| null` | An image file object. When setting, pass an upload UUID from the Uploads API (https://api.planningcenteronline.com/docs/overview/file-uploads) or a signed_identifier from an existing File. |
| `attach_youtube_thumbnail_job_id` | `string \| null` |  |
| `church_center_url` | `string \| null` |  |
| `created_at` | `string \| null` |  |
| `description` | `string \| null` |  |
| `library_audio_url` | `string \| null` |  |
| `library_streaming_service` | `string \| null` | Possible values: `vimeo`, `youtube`, `livestream_com`, `resi`, `facebook`, or `boxcast` |
| `library_video_embed_code` | `string \| null` |  |
| `library_video_thumbnail_url` | `string \| null` |  |
| `library_video_url` | `string \| null` |  |
| `needs_library_audio_or_video_url` | `boolean \| null` |  |
| `needs_notes_template` | `boolean \| null` |  |
| `needs_video_url` | `boolean \| null` |  |
| `page_actions` | `unknown[] \| null` |  |
| `published_live_at` | `string \| null` |  |
| `published_to_library_at` | `string \| null` |  |
| `sermon_audio` | `Record<string, unknown> \| null` | An audio file object. When setting, pass an upload UUID from the Uploads API (https://api.planningcenteronline.com/docs/overview/file-uploads) or a signed_identifier from an existing File. |
| `services_plan_remote_identifier` | `string \| null` | The id for the associated Services Plan (https://developer.planning.center/docs/#/apps/services/2018-08-01/vertices/plan) |
| `services_service_type_remote_identifier` | `string \| null` | The id for the associated Services Service Type (https://developer.planning.center/docs/#/apps/services/2018-08-01/vertices/service_type) |
| `stream_type` | `string \| null` | Possible values: `channel_default_livestream`, `livestream`, or `prerecorded` |
| `streaming_service` | `string \| null` | Possible values: `vimeo`, `youtube`, `livestream_com`, `resi`, `facebook`, or `boxcast` |
| `summary` | `string \| null` | The description as HTML, limited to paragraphs, line breaks, bold, and italics. Setting it also replaces description with its plain text. |
| `title` | `string \| null` |  |
| `updated_at` | `string \| null` |  |
| `video_embed_code` | `string \| null` |  |
| `video_thumbnail_url` | `string \| null` |  |
| `video_url` | `string \| null` |  |

## Relationships and includes

Side-load with `include()` (or `get({ include })`) and read with `related(resource, name)`: `channel`, `episode_resources`, `episode_times`, `note_template`, `series`, `speakerships`.

| Relationship | Type | To | Includable |
| --- | --- | --- | --- |
| `series` | To one | [Series](/reference/publishing/series/) | Yes |

## Querying

### Where

`where(field, value)` for equality; `where(field, op, value)` with the operators listed.

| Field | Value type | Operators |
| --- | --- | --- |
| `series_id` | `string \| number` | Equality only |
| `services_plan_remote_identifier` | `string` | Equality only |
| `services_service_type_remote_identifier` | `string` | Equality only |

### Order

`order(...)` accepts these fields, ascending, or descending with a `-` prefix: `published_live_at`, `published_to_library_at`, `stream_type`, `title`.

### Filters

`filter(...)` names depend on the edge you query through:

| Edge | Filters |
| --- | --- |
| `pco.publishing.episodes` | `connected_to_services`, `not_connected_to_services`, `not_published_live`, `published_live`, `published_on_church_center` |
| `episodes` on [Channel](/reference/publishing/channel/) | `connected_to_services`, `not_connected_to_services`, `not_published`, `published`, `published_to_library` |

## Edges

Follow these from one Episode, `ref = pco.publishing.episodes.id(episodeId)`:

| Edge | Leads to | Returns | Filters | Create |
| --- | --- | --- | --- | --- |
| `ref.channel` | [Channel](/reference/publishing/channel/) | Collection |  | No |
| `ref.episode_resources` | [EpisodeResource](/reference/publishing/episode-resource/) | Collection |  | Yes |
| `ref.episode_times` | [EpisodeTime](/reference/publishing/episode-time/) | Collection |  | Yes |
| `ref.note_template` | [NoteTemplate](/reference/publishing/note-template/) | Single resource |  | No |
| `ref.series` | [Series](/reference/publishing/series/) | Collection |  | No |
| `ref.speakerships` | [Speakership](/reference/publishing/speakership/) | Collection |  | No |

## Writing

| Property | Value |
| --- | --- |
| Create | Yes, `create()` on `pco.publishing.episodes` |
| Update | Yes, `update()` on a reference |
| Delete | Yes, `delete()` on a reference |

### Create attributes

Typed as `Publishing.EpisodeSchema['create']`.

| Attribute | Type |
| --- | --- |
| `art` | `Record<string, unknown> \| null` |
| `attach_youtube_thumbnail` | `unknown` |
| `channel_id` | `string` |
| `description` | `string \| null` |
| `library_audio_url` | `string \| null` |
| `library_video_url` | `string \| null` |
| `published_to_library_at` | `string \| null` |
| `series_id` | `string` |
| `sermon_audio` | `Record<string, unknown> \| null` |
| `stream_type` | `string \| null` |
| `summary` | `string \| null` |
| `title` | `string \| null` |
| `video_url` | `string \| null` |

### Update attributes

Typed as `Publishing.EpisodeSchema['update']`.

| Attribute | Type |
| --- | --- |
| `art` | `Record<string, unknown> \| null` |
| `attach_youtube_thumbnail` | `unknown` |
| `channel_id` | `string` |
| `description` | `string \| null` |
| `library_audio_url` | `string \| null` |
| `library_video_url` | `string \| null` |
| `published_to_library_at` | `string \| null` |
| `series_id` | `string` |
| `sermon_audio` | `Record<string, unknown> \| null` |
| `stream_type` | `string \| null` |
| `summary` | `string \| null` |
| `title` | `string \| null` |
| `video_url` | `string \| null` |

See [Writing data](/guides/writing-data/).

## Actions

Run with `ref.action(name, body?)`. Bodies are untyped: see Planning Center's docs for each action.

| Action | Path | Description |
| --- | --- | --- |
| `generate_download_url` | `POST /publishing/v2/episodes/{episode_id}/generate_download_url` | Generate a signed download URL for an episode's sermon audio file. |

## Example

```ts
import type { Publishing } from '@mackenly/planningcenterkit';

const page = await pco.publishing.episodes.order('published_live_at').perPage(25).list();
const items: Publishing.Episode[] = page.data;
```

Source: https://planningcenterkit.mackenly.com/reference/publishing/episode/index.mdx
