# Saved playlists

Store source links with private, unlisted, or public visibility.

Saved playlists belong to an API account. They hold source links rather than stored copies of the media. Each account can create 5 playlists with 50 items per playlist.

## Playlist routes

All writes require the owner. `GET /playlists` lists the caller's playlists. Reads of a specific public or unlisted playlist do not require authentication; private reads require the owner.

| Method | Route            | Body                                           | Success                                    |
| ------ | ---------------- | ---------------------------------------------- | ------------------------------------------ |
| GET    | `/playlists`     | None                                           | `200` with `{ playlists }`                 |
| POST   | `/playlists`     | See create example below | `201` with `{ playlist }`                  |
| GET    | `/playlists/:id` | None                                           | `200` with `{ playlist }`, including items |
| PATCH  | `/playlists/:id` | Any of `name`, `description`, `visibility`     | `200` with `{ playlist }`                  |
| DELETE | `/playlists/:id` | None                                           | `204`, no body                             |

`name` is trimmed and must contain 1 to 100 characters. `description` is at most 1000 characters. An update must contain at least one allowed field. Unknown fields are rejected.

## Visibility

| Value      | Reading behavior                                          |
| ---------- | --------------------------------------------------------- |
| `private`  | Owner only                                                |
| `unlisted` | Anyone with its ID/link; excluded from the public listing |
| `public`   | Anyone; eligible for the public listing                   |

Sharing does not grant editing rights or permission to download as the owner. Use `GET /playlists/public?limit=20` for the public listing. `limit` is 1 to 50; pass the returned `nextCursor` as `cursor` for the next page when present.

## Item routes

| Method | Route                          | Body                                                                                               | Success                       |
| ------ | ------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------- |
| POST   | `/playlists/:id/items`         | See add-links example below | `200` with `{ items, added }` |
| PATCH  | `/playlists/:id/items/:itemId` | `title`, `mediaType`, or both                                                                      | `200` with `{ item }`         |
| DELETE | `/playlists/:id/items/:itemId` | None                                                                                               | `204`, no body                |

An add request contains 1 to 50 item objects and must fit the playlist's remaining capacity. Each URL is HTTP(S), up to 4096 characters, without embedded credentials. `title` is optional, up to 200 characters. `mediaType` is `auto` (default), `video`, `audio`, or `image`.

## Download selected links

`POST /playlists/:id/download` requires the owner. Use the actual item IDs returned by the playlist, not media URLs or file IDs.

```json
{
    "itemIds": [
        "pli_example"
    ],
    "output": {
        "type": "auto",
        "format": "original",
        "quality": "best"
    }
}
```

Select 1 to 10 unique item IDs. `output` is optional. The response is `202` with a batch; follow [batch status](/docs/en/reference/batches). This does not download files immediately or create a ZIP.

If you use a single partner key for your bot, these are your partner account's playlists. They are not automatically separated by Discord member.

## Request examples

Choose a language. JavaScript and Node.js examples use a server environment, not a public browser key. Replace illustrative IDs with your own.

### Create a playlist

```request
{
    "method": "POST",
    "path": "/playlists",
    "body": {
        "name": "Saved",
        "visibility": "private"
    }
}
```

### Update a playlist

```request
{
    "method": "PATCH",
    "path": "/playlists/pl_example",
    "body": {
        "name": "Updated name",
        "visibility": "unlisted"
    }
}
```

### Add source links

```request
{
    "method": "POST",
    "path": "/playlists/pl_example/items",
    "body": {
        "items": [
            {
                "url": "https://example.com/video.mp4",
                "mediaType": "video"
            }
        ]
    }
}
```

### Delete a playlist

```request
{
    "method": "DELETE",
    "path": "/playlists/pl_example"
}
```