Creating a Playlist

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).
• At least one existing audio clip. See the creating an audio clip tutorial.

1. Create a playlist

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

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

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:

{
  "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:

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

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

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

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.