Playlists

Put videos in order, choose who can watch, and embed them with one iframe that plays them in turn, with a list beside the player to pick from.

Make a playlist

In the dashboard, open Videos, then Playlists, and choose New playlist. Give it a title, an optional description and a visibility, then Add videos from the app. Drag videos to reorder them, or use the arrows; changes save as you make them. A playlist holds up to 200 of the app's own videos, each once, and an app can have up to 500 playlists.

Deleting a video takes it out of every playlist. Deleting a playlist leaves its videos as they were.

Embed it

The playlist's Embed card has the code to copy. The page plays the first video, moves on to the next when one ends, and highlights the one playing. The list sits beside the player in a wide frame and below it in a narrow one.

Embed code
1
2
3
4
5
6
7
<iframe
  src="https://fileboy.io/video/playlist/PLAYLIST_ID/embed"
  title="Getting started"
  style="width: 100%; aspect-ratio: 16 / 9; border: 0;"
  allow="autoplay; fullscreen; picture-in-picture"
  allowfullscreen
></iframe>

Add options to the URL: autoplay=1 (muted, as browsers require), muted=1, loop=1 to start again after the last video, autoadvance=0 to stop after each one, and video=VIDEO_ID to start on a particular video.

The page uses your app's player branding and is kept out of search results. It follows allowed embed domains: it can be framed only on sites where every video in the playlist can be.

Who sees what

A playlist has its own visibility. Public and Unlisted playlists play for anyone with the link. Fileboy doesn't list playlists anywhere, so the two behave the same; use unlisted for ones you leave out of your own lists. Private playlists only play from a URL signed with your private key (scope playlist): sign the embed page URL with signUrl in any Fileboy SDK and the page passes the signature on. New playlists are private in apps that require signed reads, and public otherwise.

Each video in a playlist still follows its own visibility. Without a signature:

  • Public and unlisted videos are listed and play.
  • Password videos are listed as locked, with no name, poster or length. Picking one asks for its password, and auto-advance goes past it.
  • Private videos are left out, and not counted. That includes every video that follows an app that requires signed reads.

With a signed URL for the playlist, or your private key, every video is listed and plays: the answer carries a signed query for each private or password video, with the playlist signature's expiry and address range. So a playlist never shows a viewer more than its videos would on their own, and a signed playlist link is your say-so for everything in it.

A playlist signature covers whatever is in the playlist each time it is read, not what was in it when you signed: a video you add later plays under signatures you have already handed out, until they expire. The query each item carries opens the same reads as signing that video yourself (its stream, poster, captions, chapters, thumbnails and player config). So keep playlist signatures short-lived, and take a private video out of a playlist, or sign again, if the people holding a link shouldn't see it.

A private video's files never appear in a playlist's answer: players only get the video's own routes, which check the video's visibility on every request.

Get a playlist

What players read: the playlist and the videos this reader may see, in order. Each item has a query to put on every URL of that video (as <fileboy-player signed-query>), empty when none is needed. A private playlist needs a signature (401 playlist_private without), and a bad signature is refused whatever the visibility. Answers Cache-Control: private, no-cache.

GET
1
https://api.fileboy.io/playlists/{id}

URL Params

id string

The playlist id.

Response

data.id string

The playlist id.

data.title string

Its title.

data.visibility string

public, unlisted or private.

data.embedUrl string

Its embed page.

data.items array

Its videos in order, see Who sees what.

data.items[].access string

open, or password for a locked password video.

data.items[].query string

fb_exp, fb_ip and fb_sig for a private or password video in a signed read.

Example

REQUEST
1
curl https://api.fileboy.io/playlists/PLAYLIST_ID
RESPONSE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "data": {
    "id": "PLAYLIST_ID",
    "title": "Getting started",
    "description": null,
    "visibility": "public",
    "itemCount": 2,
    "embedUrl": "https://fileboy.io/video/playlist/PLAYLIST_ID/embed",
    "createdAt": "2026-11-16T22:00:00Z",
    "updatedAt": "2026-11-16T22:05:00Z",
    "items": [
      {
        "videoId": "VIDEO_ID",
        "access": "open",
        "visibility": "public",
        "name": "Welcome",
        "duration": 95.5,
        "extractionStatus": "done",
        "posterUrl": "https://api.fileboy.io/videos/VIDEO_ID/poster",
        "query": ""
      },
      {
        "videoId": "LOCKED_VIDEO_ID",
        "access": "password",
        "visibility": "password",
        "name": null,
        "duration": null,
        "extractionStatus": null,
        "posterUrl": null,
        "query": ""
      }
    ]
  }
}

List playlists

The app's playlists, newest first, without their items. Needs your private key.

GET
1
https://api.fileboy.io/playlists

Response

data[].id string

The playlist id.

data[].itemCount number

How many videos it holds.

Example

REQUEST
1
curl https://api.fileboy.io/playlists -H "Authorization: token 0000000...."
RESPONSE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "data": [
    {
      "id": "PLAYLIST_ID",
      "title": "Getting started",
      "description": null,
      "visibility": "public",
      "itemCount": 2,
      "embedUrl": "https://fileboy.io/video/playlist/PLAYLIST_ID/embed",
      "createdAt": "2026-11-16T22:00:00Z",
      "updatedAt": "2026-11-16T22:05:00Z"
    }
  ]
}

Create a playlist

Needs your private key. Only the app's own videos go in (404 video_not_found otherwise).

POST
1
https://api.fileboy.io/playlists

Body

title string

1 to 200 characters.

description string, optional

Up to 2000 characters.

visibility string, optional

public, unlisted or private.

videoIds array, optional

Its first videos, in order.

Response

data.id string

The playlist id.

data.title string

Its title.

data.visibility string

public, unlisted or private.

data.embedUrl string

Its embed page.

data.items array

Its videos in order, see Who sees what.

Example

REQUEST
1
curl -X POST https://api.fileboy.io/playlists -H "Authorization: token 0000000...." -H "Content-Type: application/json" -d '{"title": "Getting started", "videoIds": ["VIDEO_ID"]}'
SDKs
1
2
3
4
5
6
7
8
9
10
11
12
13
// Node (Ruby, Python and PHP have the same methods in their own style)
const playlist = await fileboy.createPlaylist({
  title: "Getting started",
  visibility: "public",
  videoIds: [introId, demoId],
})
await fileboy.addPlaylistItem(playlist.id, outroId)
await fileboy.setPlaylistItems(playlist.id, [demoId, introId, outroId]) // reorder
await fileboy.removePlaylistItem(playlist.id, demoId)
await fileboy.updatePlaylist(playlist.id, { visibility: "private" })

// A private playlist's embed page, signed for an hour
const src = fileboy.signUrl(playlist.embedUrl, { expiresIn: 3600 })
RESPONSE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "data": {
    "id": "PLAYLIST_ID",
    "title": "Getting started",
    "description": null,
    "visibility": "public",
    "itemCount": 2,
    "embedUrl": "https://fileboy.io/video/playlist/PLAYLIST_ID/embed",
    "createdAt": "2026-11-16T22:00:00Z",
    "updatedAt": "2026-11-16T22:05:00Z",
    "items": [
      {
        "videoId": "VIDEO_ID",
        "access": "open",
        "visibility": "public",
        "name": "Welcome",
        "duration": 95.5,
        "extractionStatus": "done",
        "posterUrl": "https://api.fileboy.io/videos/VIDEO_ID/poster",
        "query": ""
      },
      {
        "videoId": "LOCKED_VIDEO_ID",
        "access": "password",
        "visibility": "password",
        "name": null,
        "duration": null,
        "extractionStatus": null,
        "posterUrl": null,
        "query": ""
      }
    ]
  }
}

Change a playlist

Change its title, description (null removes it) or visibility. Needs your private key.

PATCH
1
https://api.fileboy.io/playlists/{id}

URL Params

id string

The playlist id.

Body

title string, optional

A new title.

description string | null, optional

A new description, or null.

visibility string, optional

public, unlisted or private.

Response

data.id string

The playlist id.

data.title string

Its title.

data.visibility string

public, unlisted or private.

data.embedUrl string

Its embed page.

data.items array

Its videos in order, see Who sees what.

Example

REQUEST
1
curl -X PATCH https://api.fileboy.io/playlists/PLAYLIST_ID -H "Authorization: token 0000000...." -H "Content-Type: application/json" -d '{"visibility": "private"}'
RESPONSE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "data": {
    "id": "PLAYLIST_ID",
    "title": "Getting started",
    "description": null,
    "visibility": "public",
    "itemCount": 2,
    "embedUrl": "https://fileboy.io/video/playlist/PLAYLIST_ID/embed",
    "createdAt": "2026-11-16T22:00:00Z",
    "updatedAt": "2026-11-16T22:05:00Z",
    "items": [
      {
        "videoId": "VIDEO_ID",
        "access": "open",
        "visibility": "public",
        "name": "Welcome",
        "duration": 95.5,
        "extractionStatus": "done",
        "posterUrl": "https://api.fileboy.io/videos/VIDEO_ID/poster",
        "query": ""
      },
      {
        "videoId": "LOCKED_VIDEO_ID",
        "access": "password",
        "visibility": "password",
        "name": null,
        "duration": null,
        "extractionStatus": null,
        "posterUrl": null,
        "query": ""
      }
    ]
  }
}

Set or reorder a playlist's videos

Replaces the whole list with these videos in this order; [] empties it. Needs your private key.

PUT
1
https://api.fileboy.io/playlists/{id}/items

URL Params

id string

The playlist id.

Body

videoIds array

Every video, in order, each once.

Response

data.id string

The playlist id.

data.title string

Its title.

data.visibility string

public, unlisted or private.

data.embedUrl string

Its embed page.

data.items array

Its videos in order, see Who sees what.

Example

REQUEST
1
curl -X PUT https://api.fileboy.io/playlists/PLAYLIST_ID/items -H "Authorization: token 0000000...." -H "Content-Type: application/json" -d '{"videoIds": ["SECOND_ID", "FIRST_ID"]}'
RESPONSE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "data": {
    "id": "PLAYLIST_ID",
    "title": "Getting started",
    "description": null,
    "visibility": "public",
    "itemCount": 2,
    "embedUrl": "https://fileboy.io/video/playlist/PLAYLIST_ID/embed",
    "createdAt": "2026-11-16T22:00:00Z",
    "updatedAt": "2026-11-16T22:05:00Z",
    "items": [
      {
        "videoId": "VIDEO_ID",
        "access": "open",
        "visibility": "public",
        "name": "Welcome",
        "duration": 95.5,
        "extractionStatus": "done",
        "posterUrl": "https://api.fileboy.io/videos/VIDEO_ID/poster",
        "query": ""
      },
      {
        "videoId": "LOCKED_VIDEO_ID",
        "access": "password",
        "visibility": "password",
        "name": null,
        "duration": null,
        "extractionStatus": null,
        "posterUrl": null,
        "query": ""
      }
    ]
  }
}

Add a video

At the end, or at position (from 0). 409 video_already_in_playlist when it is in already. Needs your private key.

POST
1
https://api.fileboy.io/playlists/{id}/items

URL Params

id string

The playlist id.

Body

videoId string

One of the app's videos.

position number, optional

Where to put it, from 0.

Response

data.id string

The playlist id.

data.title string

Its title.

data.visibility string

public, unlisted or private.

data.embedUrl string

Its embed page.

data.items array

Its videos in order, see Who sees what.

Example

REQUEST
1
curl -X POST https://api.fileboy.io/playlists/PLAYLIST_ID/items -H "Authorization: token 0000000...." -H "Content-Type: application/json" -d '{"videoId": "VIDEO_ID", "position": 0}'
RESPONSE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "data": {
    "id": "PLAYLIST_ID",
    "title": "Getting started",
    "description": null,
    "visibility": "public",
    "itemCount": 2,
    "embedUrl": "https://fileboy.io/video/playlist/PLAYLIST_ID/embed",
    "createdAt": "2026-11-16T22:00:00Z",
    "updatedAt": "2026-11-16T22:05:00Z",
    "items": [
      {
        "videoId": "VIDEO_ID",
        "access": "open",
        "visibility": "public",
        "name": "Welcome",
        "duration": 95.5,
        "extractionStatus": "done",
        "posterUrl": "https://api.fileboy.io/videos/VIDEO_ID/poster",
        "query": ""
      },
      {
        "videoId": "LOCKED_VIDEO_ID",
        "access": "password",
        "visibility": "password",
        "name": null,
        "duration": null,
        "extractionStatus": null,
        "posterUrl": null,
        "query": ""
      }
    ]
  }
}

Remove a video

Takes the video out of the playlist; the video stays. Needs your private key.

DELETE
1
https://api.fileboy.io/playlists/{id}/items/{videoId}

URL Params

id string

The playlist id.

videoId string

The video id.

Response

data.id string

The playlist id.

data.title string

Its title.

data.visibility string

public, unlisted or private.

data.embedUrl string

Its embed page.

data.items array

Its videos in order, see Who sees what.

Example

REQUEST
1
curl -X DELETE https://api.fileboy.io/playlists/PLAYLIST_ID/items/VIDEO_ID -H "Authorization: token 0000000...."
RESPONSE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "data": {
    "id": "PLAYLIST_ID",
    "title": "Getting started",
    "description": null,
    "visibility": "public",
    "itemCount": 2,
    "embedUrl": "https://fileboy.io/video/playlist/PLAYLIST_ID/embed",
    "createdAt": "2026-11-16T22:00:00Z",
    "updatedAt": "2026-11-16T22:05:00Z",
    "items": [
      {
        "videoId": "VIDEO_ID",
        "access": "open",
        "visibility": "public",
        "name": "Welcome",
        "duration": 95.5,
        "extractionStatus": "done",
        "posterUrl": "https://api.fileboy.io/videos/VIDEO_ID/poster",
        "query": ""
      },
      {
        "videoId": "LOCKED_VIDEO_ID",
        "access": "password",
        "visibility": "password",
        "name": null,
        "duration": null,
        "extractionStatus": null,
        "posterUrl": null,
        "query": ""
      }
    ]
  }
}

Delete a playlist

Its embed page stops working; its videos stay. Answers 204. Needs your private key.

DELETE
1
https://api.fileboy.io/playlists/{id}

URL Params

id string

The playlist id.

Example

REQUEST
1
curl -X DELETE https://api.fileboy.io/playlists/PLAYLIST_ID -H "Authorization: token 0000000...."
RESPONSE
1
204 No Content