# Creating a Playlist

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

How to create and manage audio playlists using the Audio Center API.

A playlist is an ordered collection of audio clips. Use playlists to group related clips together, for example, a series of news segments, a curated listening experience, or chapters of an audiobook.

## Prerequisites

- An Arc XP API token (see the [Developer Center](https://dev.arcxp.com/api/accessing-arcxp-apis/)).
- At least one existing audio clip. See the [creating an audio clip](https://dev.arcxp.com/audio-center/tutorials/creating-an-audio-clip/) tutorial.

## 1\. Create a playlist

Create a playlist by providing a list of clip IDs and their positions:

Terminal window

```bash
curl -X POST https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/playlists/ \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "clip_id": "first_clip_id", "position": 1 },
      { "clip_id": "second_clip_id", "position": 2 },
      { "clip_id": "third_clip_id", "position": 3 }
    ],
    "tags": ["morning-news", "2026-03"]
  }'
```

The API returns `201 Created` with the playlist ID and a `Location` header pointing to the new resource.

> **Note:**
> 
> Each item’s `position` must be a positive integer and unique within the playlist. Positions determine the playback order.

## 2\. Retrieve a playlist

Terminal window

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

The response includes the ordered list of items, tags, and metadata:

```json
{
  "id": "playlist_id",
  "items": [
    { "clip_id": "first_clip_id", "position": 1 },
    { "clip_id": "second_clip_id", "position": 2 },
    { "clip_id": "third_clip_id", "position": 3 }
  ],
  "tags": ["morning-news", "2026-03"],
  "circulation": { ... },
  "created_at": "2026-03-22T12:00:00Z",
  "updated_at": "2026-03-22T12:00:00Z"
}
```

## 3\. Update a playlist

Use `PATCH` to update a playlist: for example, to reorder clips, add new ones, or change tags:

Terminal window

```bash
curl -X PATCH https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/playlists/{playlist_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "clip_id": "second_clip_id", "position": 1 },
      { "clip_id": "first_clip_id", "position": 2 },
      { "clip_id": "new_clip_id", "position": 3 }
    ],
    "tags": ["morning-news", "2026-03", "updated"]
  }'
```

Returns `204 No Content` on success. Use `PUT` instead to fully replace the playlist.

## 4\. List playlists

Terminal window

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

### Filters

You can filter playlists 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`

Terminal window

```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/playlists/?include_tags=morning-news"
```

## 5\. Delete a playlist

Terminal window

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

> **Note:**
> 
> Deleting a playlist does not delete the audio clips it contains. The clips remain available independently.

## Playlist fields reference

### Create / update playlist

| Field              | Required | Description                                                                                                                                                                         |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| items              | Yes      | Array of playlist items, each with clip\_id and position.                                                                                                                           |
| items\[\].clip\_id | Yes      | The ID of an existing audio clip.                                                                                                                                                   |
| items\[\].position | Yes      | Positive integer defining playback order. Must be unique within the playlist.                                                                                                       |
| tags               | No       | Tags for organization and filtering.                                                                                                                                                |
| circulation        | No       | Which sites can access this playlist: a canonical site (cid) plus a sites set. Defaults to {cid: "global", sites: \["global"\]}, which makes the playlist accessible on every site. |
