# Creating a podcast

Source: https://dev.arcxp.com/audio-center/tutorials/creating-a-podcast/

Walkthrough of creating and managing a podcast with the Audio Center API.

This tutorial walks through creating a podcast, adding episodes, uploading audio, and publishing, all through the Arc XP Audio API.

For background on Apple’s podcast RSS requirements, see the [Apple Podcasters RSS requirements](https://podcasters.apple.com/support/823-podcast-requirements).

## Prerequisites

- An Arc XP API token (see the [Developer Center](https://dev.arcxp.com/api/accessing-arcxp-apis/)).
- Artwork for the podcast in JPEG or PNG format, between 1400×1400 and 3000×3000 pixels (see [Apple's artwork requirements](https://podcasters.apple.com/support/896-artwork-requirements)).

## 1\. Choose a Category

Categories for a podcast follow Apple’s `iTunes` category list. You can retrieve the full list of supported categories and subcategories from the API:

Terminal window

```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/meta/podcasts/categories
```

Each podcast requires 1–2 categories. For the full list of categories and their meanings, see [Apple Podcasts categories](https://podcasters.apple.com/support/1691-apple-podcasts-categories).

## 2\. Create the podcast

Create a podcast by providing channel metadata. This establishes the podcast’s RSS feed identity.

Terminal window

```bash
curl -X POST https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/ \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": {
      "title": "My Tech Podcast",
      "description": "Weekly discussions about emerging technology trends.",
      "language": "en",
      "link": "https://example.com/my-tech-podcast",
      "copyright": "© 2026 Example Corp",
      "image": {
        "href": "https://example.com/podcast-artwork.jpg"
      },
      "type": "episodic",
      "categories": [
        { "text": "Technology" }
      ],
      "explicit": "false",
      "author": "Example Corp",
      "owner": {
        "name": "Jane Doe",
        "email": "jane@example.com"
      }
    },
    "tags": ["technology", "weekly"]
  }'
```

The API returns `201 Created` with the podcast ID in the response body and a `Location` header pointing to the new resource.

### Channel Fields Reference

| Field       | Required | Description                                                                                                                |
| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| title       | Yes      | The podcast title (min 3 characters). Used in search and display.                                                          |
| description | Yes      | Show description (max 4000 characters). Supports plain text or HTML.                                                       |
| image       | Yes      | Artwork URL in JPEG or PNG format, 1400×1400 to 3000×3000 pixels.                                                          |
| categories  | Yes      | 1–2 iTunes categories (use the /meta/podcasts/categories endpoint).                                                        |
| language    | No       | [ISO 639](https://www.loc.gov/standards/iso639-2/php/code%5Flist.php) language code. Defaults to "en".                     |
| type        | No       | "episodic" (default) or "serial". See [Apple's episode type docs](https://podcasters.apple.com/support/846-episode-types). |
| explicit    | No       | "true" or "false". Defaults to "false".                                                                                    |
| author      | No       | Show author or network name.                                                                                               |
| owner       | No       | Contact name and email for the feed owner.                                                                                 |
| link        | No       | URL of the podcast’s website.                                                                                              |
| copyright   | No       | Copyright notice.                                                                                                          |

## 3\. Create an Episode

With your `podcast_id`, create an episode by providing its metadata:

Terminal window

```bash
curl -X POST https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id}/episodes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Episode 1: Getting Started",
    "description": "In this episode we cover the basics.",
    "explicit": "false",
    "episode_type": "full",
    "episode": 1,
    "season": 1
  }'
```

The API returns `201 Created` with a `Location` header containing the new episode’s URL, which includes its GUID.

### Episode Fields Reference

| Field         | Required | Description                                                                 |
| ------------- | -------- | --------------------------------------------------------------------------- |
| title         | Yes      | Episode title (3–500 characters).                                           |
| description   | Yes      | Episode description (3–4000 characters). Supports plain text or HTML.       |
| enclosure     | No       | Audio file metadata (url, length, type). Populated automatically on upload. |
| pubDate       | No       | RFC 2822 publish date. Defaults to current time.                            |
| link          | No       | URL of the episode’s web page.                                              |
| explicit      | No       | "true" or "false".                                                          |
| duration      | No       | Duration in seconds.                                                        |
| image         | No       | Episode-specific artwork URL.                                               |
| episode       | No       | Episode number. Required if you set season.                                 |
| episode\_type | No       | "full" (default), "trailer", or "bonus".                                    |
| season        | No       | Season number.                                                              |
| block         | No       | Set to "Yes" to prevent this episode from appearing in Apple Podcasts.      |

## 4\. Upload Episode Audio

Upload an audio file to the episode by using the two-step presigned-URL flow. Supported formats include WAV, MP3, FLAC, M4A, and MP4 (see the [developer guide](https://dev.arcxp.com/audio-center/developer-docs/arc-audio-api-developer-guide/#supported-file-formats) for details). First, request a presigned upload URL:

Terminal window

```bash
curl -X POST "https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id}/episodes/{episode_guid}/upload/presigned?file_name=episode1.mp3" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

The response includes an `upload_url` for the direct upload and a `notification_url` for processing updates. Upload the file bytes to the returned URL as a second step:

Terminal window

```bash
curl -X PUT "PRESIGNED_UPLOAD_URL" \
  -H "Content-Type: audio/mp3" \
  --upload-file /path/to/your/file.mp3
```

The presigned URL’s signature covers `Content-Type: audio/{extension}`, where `extension` denotes the file extension you passed as `file_name` (for example, `audio/wav`, `audio/flac`, `audio/m4a`, or `audio/mp4` for a video file uploaded for audio extraction). This value must match the `Content-Type` header on your `PUT` request exactly, or the upload fails with a signature error.

### Track progress with Server-Sent Events (SSE)

Subscribe to the `notification_url` returned earlier to receive Server-Sent Events (SSE) with progress notifications such as `encoding_started`, `encoding_analyzing`, and `encoding_complete` (or `encoding_failed`). You can also retrieve the episode record at any time to check its processing status.

## 5\. Publish the Episode

Once the episode’s audio is in `ready` state, publish it:

Terminal window

```bash
curl -X POST https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id}/episodes/{episode_guid}/publish \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Returns `202 Accepted`. Publishing the episode also makes the podcast’s RSS feed available publicly, and the newly published episode will appear in that feed after publishing completes.

## 6\. Optionally publish the podcast record

You do not need this step to make the RSS feed public if you have already published an episode. Publishing an episode automatically creates and publishes the podcast’s RSS feed with only the episodes you have individually published.

Publish the podcast record directly only if you want to explicitly publish the show metadata itself:

Terminal window

```bash
curl -X POST https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id}/publish \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Returns `202 Accepted`. In most workflows, publishing an episode satisfies this step before you submit the RSS feed URL to directories such as [Apple Podcasts](https://podcasters.apple.com/) and Spotify.

> **Tip:**
> 
> Publish episodes before publishing the podcast so that listeners see content when they first discover your feed.

## Manage your podcast

### Update podcast metadata

Use `PATCH` to update specific fields, or `PUT` to replace the entire podcast record:

Terminal window

```bash
curl -X PATCH https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": {
      "title": "My Tech Podcast - Season 2",
      "description": "Updated description for the new season.",
      "image": { "href": "https://example.com/new-artwork.jpg" },
      "categories": [{ "text": "Technology" }]
    }
  }'
```

Returns `204 No Content` on success.

### Unpublish content

To remove a podcast or episode from public availability:

Terminal window

```bash
# Unpublish a single episode
curl -X POST https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id}/episodes/{episode_guid}/unpublish \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Unpublish the entire podcast
curl -X POST https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id}/unpublish \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Delete a podcast

Terminal window

```bash
curl -X DELETE https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Returns `204 No Content`. The API marks associated audio binaries for removal and permanently purges them within 30 days.

### List and Retrieve Podcasts

Terminal window

```bash
# List all podcasts
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/

# Get a specific podcast
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id}

# List all episodes for a podcast
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id}/episodes

# Get a specific episode
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/podcasts/{podcast_id}/episodes/{episode_guid}
```

### Filter podcasts

You can filter the podcast list by using query parameters:

- `include_tags` / `exclude_tags`: Filter by tags
- `sites`: Filter by site IDs
- Date filters: `created_after`, `created_before`, `updated_after`, `updated_before`

## Extra Info

- Podcasts must have at least one episode in order for the major podcast players to accept the feed.
- Publishing an episode will also implicitly publish a podcast’s feed. For example, if your podcast has two episodes: 1 and 2, both unpublished; publishing episode 1 will also publish the podcast RSS feed, with only episode 1\. Episode 2 will remain unpublished.
