Videos

Video Playlists

Operations dealing with playlists of videos. Playlists are bound to users and/or channels.

List available playlist privacy policies

GET

https://peertube2.cpy.re/api/v1/video-playlists/privacies

List available playlist privacy policies

curl -X GET 'https://peertube2.cpy.re/api/v1/video-playlists/privacies'

const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists/privacies', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/video-playlists/privacies')
print(response.text)

200

External example: https://peertube2.cpy.re/api/v1/video-playlists/privacies

Response

200OKArray<string>

successful operation

Response fields application/json

Array<string>

List video playlists

GET

https://peertube2.cpy.re/api/v1/video-playlists

List video playlists

curl -X GET 'https://peertube2.cpy.re/api/v1/video-playlists?count=15'

const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists?count=15', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/video-playlists?count=15')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "id": 42,
      "uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z",
      "description": "string",
      "displayName": "string",
      "isLocal": true,
      "videoLength": 0,
      "thumbnailPath": "string",
      "thumbnails": [
        {
          "fileUrl": "string",
          "width": 0,
          "height": 0,
          "aspectRatio": "16:9"
        }
      ],
      "privacy": {
        "id": 1,
        "label": "string"
      },
      "type": {
        "id": 1,
        "label": "string"
      },
      "ownerAccount": {
        "id": 0,
        "name": "string",
        "displayName": "string",
        "url": "https://example.com",
        "host": "example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ]
      },
      "videoChannel": {
        "id": 42,
        "name": "string",
        "displayName": "string",
        "url": "https://example.com",
        "host": "example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ]
      },
      "videoChannelPosition": 1
    }
  ]
}

Parameters

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

sortstringquery

Sort column

playlistTypeVideoPlaylistTypeSet12query

Response

200OKobject

successful operation

Response fields application/json

totalinteger

Example

dataArray<VideoPlaylist>

Show child attributes

idid>= 1

Example

uuidUUIDv4<uuid>

Example

9c9de5e8-0a1e-484a-b099-e80766180a6d

shortUUIDshortUUID

Show child attributes

translation of a uuid v4 with a bigger alphabet to have a shorter uuid

shortUUID

Example

2y84q2MQUMWPbiEcxNXMgC

createdAtstring<date-time>

updatedAtstring<date-time>

descriptionstring

displayNamestring

isLocalboolean

videoLengthinteger>= 0

thumbnailPathstring | nulldeprecated

Deprecated in PeerTube v8.1, use thumbnails instead. Null if the file is stored in object storage: use the non-deprecated field instead.

thumbnailsArray<Thumbnail>

PeerTube >= 8.1 Array of thumbnails for the playlist

Show child attributes

fileUrlstring

widthinteger

heightinteger

aspectRatiostring

Example

16:9

privacyVideoPlaylistPrivacyConstant

Show child attributes

idVideoPlaylistPrivacySet123

Video playlist privacy policy (see /video-playlists/privacies)

labelstring

typeVideoPlaylistTypeConstant

Show child attributes

idVideoPlaylistTypeSet12

The video playlist type (Regular = 1, Watch Later = 2)

labelstring

ownerAccountAccountSummary

Show child attributes

idinteger

namestring

displayNamestring

urlstring<url>

hoststring<hostname>

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

videoChannelVideoChannelSummary

Show child attributes

idid>= 1

Example

namestring

displayNamestring

urlstring<url>

hoststring<hostname>

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

videoChannelPositioninteger>= 1

Position of the playlist in the channel

Create a video playlist

POST

https://peertube2.cpy.re/api/v1/video-playlists

If the video playlist is set as public, videoChannelId is mandatory.

Create a video playlist

curl -X POST 'https://peertube2.cpy.re/api/v1/video-playlists' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'displayName=string' \
  --form-string 'privacy=1' \
  --form-string 'description=string'

const form = new FormData();
form.append('displayName', 'string');
form.append('privacy', '1');
form.append('description', 'string');
const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('displayName', (None, 'string')),
        ('privacy', (None, '1')),
        ('description', (None, 'string')),
    ]
    response = requests.request('POST', 'https://peertube2.cpy.re/api/v1/video-playlists', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "displayName": "string",
  "thumbnailfile": "<binary>",
  "privacy": 1,
  "description": "string"
}

200

{
  "videoPlaylist": {
    "id": 42,
    "uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d"
  }
}

Body

multipart/form-data

multipart/form-dataobject

Encoding

thumbnailfileimage/jpeg

displayNamestringrequired

Video playlist display name

thumbnailfilestring<binary>

Video playlist thumbnail file

privacyVideoPlaylistPrivacySet123

Video playlist privacy policy (see /video-playlists/privacies)

descriptionstring

Video playlist description

videoChannelIdid

Video channel in which the playlist will be published

Show child attributes

id>= 1

Example

Response

200OKobject

successful operation

Response fields application/json

videoPlaylistobject

Show child attributes

idid>= 1

Example

uuidUUIDv4<uuid>

Example

9c9de5e8-0a1e-484a-b099-e80766180a6d

shortUUIDshortUUID

Show child attributes

translation of a uuid v4 with a bigger alphabet to have a shorter uuid

shortUUID

Example

2y84q2MQUMWPbiEcxNXMgC

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Get a video playlist

GET

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}

Get a video playlist

curl -X GET 'https://peertube2.cpy.re/api/v1/video-playlists/42'

const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists/42', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/video-playlists/42')
print(response.text)

200

{
  "id": 42,
  "uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
  "createdAt": "2024-01-15T09:30:00Z",
  "updatedAt": "2024-01-15T09:30:00Z",
  "description": "string",
  "displayName": "string",
  "isLocal": true,
  "videoLength": 0,
  "thumbnailPath": "string",
  "thumbnails": [
    {
      "fileUrl": "string",
      "width": 0,
      "height": 0,
      "aspectRatio": "16:9"
    }
  ],
  "privacy": {
    "id": 1,
    "label": "string"
  },
  "type": {
    "id": 1,
    "label": "string"
  },
  "ownerAccount": {
    "id": 0,
    "name": "string",
    "displayName": "string",
    "url": "https://example.com",
    "host": "example.com",
    "avatars": [
      {
        "path": "string",
        "fileUrl": "string",
        "width": 0,
        "height": 0,
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
      }
    ]
  },
  "videoChannel": {
    "id": 42,
    "name": "string",
    "displayName": "string",
    "url": "https://example.com",
    "host": "example.com",
    "avatars": [
      {
        "path": "string",
        "fileUrl": "string",
        "width": 0,
        "height": 0,
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
      }
    ]
  },
  "videoChannelPosition": 1
}

Parameters

playlistIdid>= 1requiredpath

Playlist id

Response

200OKVideoPlaylist

successful operation

Response fields application/json

idid>= 1

Example

uuidUUIDv4<uuid>

Example

9c9de5e8-0a1e-484a-b099-e80766180a6d

shortUUIDshortUUID

Show child attributes

translation of a uuid v4 with a bigger alphabet to have a shorter uuid

shortUUID

Example

2y84q2MQUMWPbiEcxNXMgC

createdAtstring<date-time>

updatedAtstring<date-time>

descriptionstring

displayNamestring

isLocalboolean

videoLengthinteger>= 0

thumbnailPathstring | nulldeprecated

Deprecated in PeerTube v8.1, use thumbnails instead. Null if the file is stored in object storage: use the non-deprecated field instead.

thumbnailsArray<Thumbnail>

PeerTube >= 8.1 Array of thumbnails for the playlist

Show child attributes

fileUrlstring

widthinteger

heightinteger

aspectRatiostring

Example

16:9

privacyVideoPlaylistPrivacyConstant

Show child attributes

idVideoPlaylistPrivacySet123

Video playlist privacy policy (see /video-playlists/privacies)

labelstring

typeVideoPlaylistTypeConstant

Show child attributes

idVideoPlaylistTypeSet12

The video playlist type (Regular = 1, Watch Later = 2)

labelstring

ownerAccountAccountSummary

Show child attributes

idinteger

namestring

displayNamestring

urlstring<url>

hoststring<hostname>

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

videoChannelVideoChannelSummary

Show child attributes

idid>= 1

Example

namestring

displayNamestring

urlstring<url>

hoststring<hostname>

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

videoChannelPositioninteger>= 1

Position of the playlist in the channel

Update a video playlist

PUT

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}

If the video playlist is set as public, the playlist must have a assigned channel.

Update a video playlist

curl -X PUT 'https://peertube2.cpy.re/api/v1/video-playlists/42' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'displayName=string' \
  --form-string 'privacy=1' \
  --form-string 'description=string'

const form = new FormData();
form.append('displayName', 'string');
form.append('privacy', '1');
form.append('description', 'string');
const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists/42', {
  method: 'PUT',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('displayName', (None, 'string')),
        ('privacy', (None, '1')),
        ('description', (None, 'string')),
    ]
    response = requests.request('PUT', 'https://peertube2.cpy.re/api/v1/video-playlists/42', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "displayName": "string",
  "thumbnailfile": "<binary>",
  "privacy": 1,
  "description": "string"
}

Body

multipart/form-data

multipart/form-dataobject

Encoding

thumbnailfileimage/jpeg

displayNamestring

Video playlist display name

thumbnailfilestring<binary>

Video playlist thumbnail file

privacyVideoPlaylistPrivacySet123

Video playlist privacy policy (see /video-playlists/privacies)

descriptionstring

Video playlist description

videoChannelIdid

Video channel in which the playlist will be published

Show child attributes

id>= 1

Example

Parameters

playlistIdid>= 1requiredpath

Playlist id

Response

204No Content

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Delete a video playlist

DELETE

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}

Delete a video playlist

curl -X DELETE 'https://peertube2.cpy.re/api/v1/video-playlists/42' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists/42', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/video-playlists/42',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

playlistIdid>= 1requiredpath

Playlist id

Response

204No Content

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

List videos of a playlist

GET

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}/videos

List videos of a playlist

curl -X GET 'https://peertube2.cpy.re/api/v1/video-playlists/42/videos?count=15'

const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists/42/videos?count=15', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/video-playlists/42/videos?count=15')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "position": 2,
      "startTimestamp": 10,
      "stopTimestamp": 41,
      "video": {
        "isLive": true,
        "liveSchedules": [
          {
            "startAt": "2024-01-15T09:30:00Z"
          }
        ],
        "createdAt": "2017-10-01T10:52:46.396Z",
        "publishedAt": "2018-10-01T10:52:46.396Z",
        "updatedAt": "2021-05-04T08:01:01.502Z",
        "originallyPublishedAt": "2010-10-01T10:52:46.396Z",
        "category": {
          "id": 15,
          "label": "Science & Technology"
        },
        "licence": {
          "id": 2,
          "label": "Attribution - Share Alike"
        },
        "language": {
          "id": "en",
          "label": "English"
        },
        "privacy": {
          "id": 1,
          "label": "string"
        },
        "truncatedDescription": "**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\\r\\n\\r\\n\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\\r\\n*A decentralized video hosting network, based on fr...\n",
        "duration": 1419,
        "aspectRatio": 1.778,
        "isLocal": true,
        "name": "What is PeerTube?",
        "thumbnailPath": "string",
        "previewPath": "string",
        "thumbnails": [
          {
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "aspectRatio": "16:9"
          }
        ],
        "embedPath": "/videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee",
        "views": 1337,
        "likes": 42,
        "dislikes": 7,
        "comments": 0,
        "nsfw": true,
        "nsfwSummary": "string",
        "aiUsage": {
          "id": 1,
          "label": "string"
        },
        "commercialContent": {
          "id": 1,
          "label": "string"
        },
        "recommendationScope": {
          "id": 1,
          "label": "string"
        },
        "waitTranscoding": true,
        "state": {
          "id": 1,
          "label": "string"
        },
        "scheduledUpdate": {
          "privacy": 1,
          "updateAt": "2024-01-15T09:30:00Z"
        },
        "blacklisted": true,
        "blacklistedReason": "string",
        "account": {
          "id": 0,
          "name": "string",
          "displayName": "string",
          "url": "https://example.com",
          "host": "example.com",
          "avatars": [
            {
              "path": "string",
              "fileUrl": "string",
              "width": 0,
              "height": 0,
              "createdAt": "2024-01-15T09:30:00Z",
              "updatedAt": "2024-01-15T09:30:00Z"
            }
          ]
        },
        "channel": {
          "id": 42,
          "name": "string",
          "displayName": "string",
          "url": "https://example.com",
          "host": "example.com",
          "avatars": [
            {
              "path": "string",
              "fileUrl": "string",
              "width": 0,
              "height": 0,
              "createdAt": "2024-01-15T09:30:00Z",
              "updatedAt": "2024-01-15T09:30:00Z"
            }
          ]
        },
        "userHistory": {
          "currentTime": 0
        },
        "captionLanguages": [
          "fr"
        ]
      }
    }
  ]
}

Parameters

playlistIdid>= 1requiredpath

Playlist id

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

Response

200OKany

successful operation

Response fields application/json

totalinteger

Example

dataArray<object>

Show child attributes

idid

Playlist element id

Show child attributes

id>= 1

Example

positioninteger

Example

startTimestampinteger<seconds> | null

Example

stopTimestampinteger<seconds> | null

Example

videoVideo

Show child attributes

idid

object id for the video

Show child attributes

id>= 1

Example

uuidUUIDv4

universal identifier for the video, that can be used across instances

Show child attributes

UUIDv4<uuid>

Example

9c9de5e8-0a1e-484a-b099-e80766180a6d

shortUUIDshortUUID

Show child attributes

translation of a uuid v4 with a bigger alphabet to have a shorter uuid

shortUUID

Example

2y84q2MQUMWPbiEcxNXMgC

isLiveboolean

liveSchedulesArray<LiveSchedule>

Show child attributes

startAtstring<date-time>

Date when the stream is scheduled to air at

createdAtstring<date-time>

time at which the video object was first drafted

Example

2017-10-01T10:52:46.396Z

publishedAtstring<date-time>

time at which the video was marked as ready for playback (with restrictions depending on privacy). Usually set after a state evolution.

Example

2018-10-01T10:52:46.396Z

updatedAtstring<date-time>

last time the video's metadata was modified

Example

2021-05-04T08:01:01.502Z

originallyPublishedAtstring<date-time> | null

used to represent a date of first publication, prior to the practical publication date of publishedAt

Example

2010-10-01T10:52:46.396Z

categoryVideoConstantNumber-Category

category in which the video is classified

Show child attributes

idVideoCategorySet

category id of the video (see /videos/categories)

Example

labelstring

Example

Science & Technology

licenceVideoConstantNumber-Licence

licence under which the video is distributed

Show child attributes

idVideoLicenceSet

licence id of the video (see /videos/licences)

Example

labelstring

Example

Attribution - Share Alike

languageVideoConstantString-Language

main language used in the video

Show child attributes

idVideoLanguageSet

language id of the video (see /videos/languages)

Example

en

labelstring

Example

English

privacyVideoPrivacyConstant

Show child attributes

idVideoPrivacySet12345

privacy id of the video (see /videos/privacies)

labelstring

truncatedDescriptionstring | null

truncated description of the video, written in Markdown.

Example

**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...

durationinteger<seconds>

duration of the video in seconds

Example

aspectRationumber<float> | null

PeerTube >= 6.1 Aspect ratio of the video stream

Example

1.778

isLocalboolean

namename

title of the video

Example

What is PeerTube?

thumbnailPathstring | nulldeprecated

Deprecated in PeerTube v8.1, use thumbnails instead. Null if the file is stored in object storage: use the non-deprecated field instead.

previewPathstring | nulldeprecated

Deprecated in PeerTube v8.1, use thumbnails instead. Null if the file is stored in object storage: use the non-deprecated field instead.

thumbnailsArray<Thumbnail>

PeerTube >= 8.1 Array of thumbnails for the video

Show child attributes

fileUrlstring

widthinteger

heightinteger

aspectRatiostring

Example

16:9

embedPathstring

Example

/videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee

viewsinteger

Example

likesinteger

Example

dislikesinteger

Example

commentsinteger

PeerTube >= 7.2 Number of comments on the video

nsfwboolean

nsfwFlagsNSFWFlag

Show child attributes

NSFW flags (can be combined using bitwise or operator)

0 NONE
1 VIOLENT
2 EXPLICIT_SEX

NSFWFlag0124

nsfwSummarystring

PeerTube >= 7.2 More information about the sensitive content of the video

aiUsageVideoAIUsageConstant

Show child attributes

idVideoAIUsageSet1234

PeerTube >= 9.0 Use of AI in the video, declared by the video creator:

1 Not specified
2 No AI-generated content: nothing seen or heard in the video has been generated by AI
3 Contains AI-generated content: some parts of the video have been generated by AI
4 AI-generated: the whole video, or most of it, has been generated by AI

labelstring

commercialContentVideoCommercialContentConstant

Show child attributes

idVideoCommercialContentSet123

PeerTube >= 9.0 Commercial content in the video, declared by the video creator:

1 None
2 Promotional content: the creator promotes their own products, services or business
3 Paid partnership: a third party paid, or provided goods or services, in exchange for the promotion

labelstring

recommendationScopeVideoRecommendationScopeConstant

Show child attributes

idVideoRecommendationScopeSet1234

Videos that can be recommended next to a video:

1 All videos
2 Only videos of the platform that owns the reference video (or of the current platform if no video is given)
3 Only videos of the account that owns the reference video
4 Only videos of the channel of the reference video

This is a preference of the video owner: applications displaying recommendations may not apply it

labelstring

waitTranscodingboolean | null

stateVideoStateConstant

represents the internal state of the video processing within the PeerTube instance

Show child attributes

idid123456789101112131415

The video state:

1: Published
2: To transcode
3: To import
4: Waiting for live stream
5: Live ended
6: To move to an external storage (object storage...)
7: Transcoding failed
8: Moving to an external storage failed
9: To edit using studio edition feature
10: To move to the file system
11: Moving to the file system failed
12: Import failed
13: To duplicate, the files of another video are being copied
14: Duplication failed, the files of the other video could not be copied
15: The studio edition of a video saved as a new video failed

Same fields as data.id

labelstring

scheduledUpdateVideoScheduledUpdate | null

Show child attributes

privacyVideoPrivacySet12345

privacy id of the video (see /videos/privacies)

updateAtstring<date-time>required

When to update the video

blacklistedboolean | null

blacklistedReasonstring | null

accountAccountSummary

Show child attributes

idinteger

namestring

displayNamestring

urlstring<url>

hoststring<hostname>

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

channelVideoChannelSummary

Show child attributes

idid>= 1

Example

Same fields as data.id

namestring

displayNamestring

urlstring<url>

hoststring<hostname>

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

userHistoryobject | null

Show child attributes

currentTimeinteger

captionLanguagesArray<string>

PeerTube >= 9.0 Languages of the video captions. Only returned by video lists

Add a video in a playlist

POST

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}/videos

Add a video in a playlist

curl -X POST 'https://peertube2.cpy.re/api/v1/video-playlists/42/videos' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "startTimestamp": 0,
  "stopTimestamp": 0
}'

const body = `{
  "startTimestamp": 0,
  "stopTimestamp": 0
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists/42/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "startTimestamp": 0,
  "stopTimestamp": 0
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/video-playlists/42/videos',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "startTimestamp": 0,
  "stopTimestamp": 0
}

200

{
  "videoPlaylistElement": {
    "id": 2
  }
}

Body

application/json

videoIdUUIDv4 | idrequired

Video to add in the playlist

Show child attributes

One of

universal identifier for the video, that can be used across instances

UUIDv4<uuid>

Example

9c9de5e8-0a1e-484a-b099-e80766180a6d

object id for the video

id>= 1

Example

startTimestampinteger<seconds>

Start the video at this specific timestamp

stopTimestampinteger<seconds>

Stop the video at this specific timestamp

Parameters

playlistIdid>= 1requiredpath

Playlist id

Response

200OKobject

successful operation

Response fields application/json

videoPlaylistElementobject

Show child attributes

idinteger

Example

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Reorder playlist elements

POST

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}/videos/reorder

Reorder playlist elements

curl -X POST 'https://peertube2.cpy.re/api/v1/video-playlists/42/videos/reorder' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "startPosition": 1,
  "insertAfterPosition": 0,
  "reorderLength": 1
}'

const body = `{
  "startPosition": 1,
  "insertAfterPosition": 0,
  "reorderLength": 1
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists/42/videos/reorder', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "startPosition": 1,
  "insertAfterPosition": 0,
  "reorderLength": 1
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/video-playlists/42/videos/reorder',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "startPosition": 1,
  "insertAfterPosition": 0,
  "reorderLength": 1
}

Body

application/json

startPositioninteger>= 1required

Start position of the element to reorder

insertAfterPositioninteger>= 0required

New position for the block to reorder, to add the block before the first element

reorderLengthinteger>= 1

How many element from startPosition to reorder

Parameters

playlistIdid>= 1requiredpath

Playlist id

Response

204No Content

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Update a playlist element

PUT

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}/videos/{playlistElementId}

Update a playlist element

curl -X PUT 'https://peertube2.cpy.re/api/v1/video-playlists/42/videos/42' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "startTimestamp": 0,
  "stopTimestamp": 0
}'

const body = `{
  "startTimestamp": 0,
  "stopTimestamp": 0
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists/42/videos/42', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "startTimestamp": 0,
  "stopTimestamp": 0
}'''

response = requests.put(
    'https://peertube2.cpy.re/api/v1/video-playlists/42/videos/42',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "startTimestamp": 0,
  "stopTimestamp": 0
}

Body

application/json

startTimestampinteger<seconds>

Start the video at this specific timestamp

stopTimestampinteger<seconds>

Stop the video at this specific timestamp

Parameters

playlistIdid>= 1requiredpath

Playlist id

playlistElementIdid>= 1requiredpath

Playlist element id

Response

204No Content

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Delete an element from a playlist

DELETE

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}/videos/{playlistElementId}

Delete an element from a playlist

curl -X DELETE 'https://peertube2.cpy.re/api/v1/video-playlists/42/videos/42' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/video-playlists/42/videos/42', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/video-playlists/42/videos/42',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

playlistIdid>= 1requiredpath

Playlist id

playlistElementIdid>= 1requiredpath

Playlist element id

Response

204No Content

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Check video exists in my playlists

GET

https://peertube2.cpy.re/api/v1/users/me/video-playlists/videos-exist

Check video exists in my playlists

curl -X GET 'https://peertube2.cpy.re/api/v1/users/me/video-playlists/videos-exist' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/users/me/video-playlists/videos-exist', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://peertube2.cpy.re/api/v1/users/me/video-playlists/videos-exist',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "videoId": [
    {
      "playlistElementId": 0,
      "playlistId": 0,
      "startTimestamp": 0,
      "stopTimestamp": 0
    }
  ]
}

Parameters

videoIdsArray<id>requiredquery

The video ids to check

Response

200OKobject

successful operation

Response fields application/json

videoIdArray<object>

Show child attributes

playlistElementIdinteger

playlistIdinteger

startTimestampinteger<seconds> | null

stopTimestampinteger<seconds> | null

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Search playlists

GET

https://peertube2.cpy.re/api/v1/search/video-playlists

Search playlists

curl -X GET 'https://peertube2.cpy.re/api/v1/search/video-playlists?search=string&count=15'

const response = await fetch('https://peertube2.cpy.re/api/v1/search/video-playlists?search=string&count=15', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/search/video-playlists?search=string&count=15')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "id": 42,
      "uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z",
      "description": "string",
      "displayName": "string",
      "isLocal": true,
      "videoLength": 0,
      "thumbnailPath": "string",
      "thumbnails": [
        {
          "fileUrl": "string",
          "width": 0,
          "height": 0,
          "aspectRatio": "16:9"
        }
      ],
      "privacy": {
        "id": 1,
        "label": "string"
      },
      "type": {
        "id": 1,
        "label": "string"
      },
      "ownerAccount": {
        "id": 0,
        "name": "string",
        "displayName": "string",
        "url": "https://example.com",
        "host": "example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ]
      },
      "videoChannel": {
        "id": 42,
        "name": "string",
        "displayName": "string",
        "url": "https://example.com",
        "host": "example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ]
      },
      "videoChannelPosition": 1
    }
  ]
}

Parameters

searchstringrequiredquery

String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete playlist information and interact with it.

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

searchTargetstringlocalsearch-indexquery

If the administrator enabled search index support, you can override the default search target.

Warning: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information:

If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API

sortstringquery

Sort column

hoststringquery

Find elements owned by this host

uuidsanyquery

Find elements with specific UUIDs

Response

200OKobject

successful operation

Response fields application/json

totalinteger

Example

dataArray<VideoPlaylist>

Show child attributes

idid>= 1

Example

uuidUUIDv4<uuid>

Example

9c9de5e8-0a1e-484a-b099-e80766180a6d

shortUUIDshortUUID

Show child attributes

translation of a uuid v4 with a bigger alphabet to have a shorter uuid

shortUUID

Example

2y84q2MQUMWPbiEcxNXMgC

createdAtstring<date-time>

updatedAtstring<date-time>

descriptionstring

displayNamestring

isLocalboolean

videoLengthinteger>= 0

thumbnailPathstring | nulldeprecated

Deprecated in PeerTube v8.1, use thumbnails instead. Null if the file is stored in object storage: use the non-deprecated field instead.

thumbnailsArray<Thumbnail>

PeerTube >= 8.1 Array of thumbnails for the playlist

Show child attributes

fileUrlstring

widthinteger

heightinteger

aspectRatiostring

Example

16:9

privacyVideoPlaylistPrivacyConstant

Show child attributes

idVideoPlaylistPrivacySet123

Video playlist privacy policy (see /video-playlists/privacies)

labelstring

typeVideoPlaylistTypeConstant

Show child attributes

idVideoPlaylistTypeSet12

The video playlist type (Regular = 1, Watch Later = 2)

labelstring

ownerAccountAccountSummary

Show child attributes

idinteger

namestring

displayNamestring

urlstring<url>

hoststring<hostname>

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

videoChannelVideoChannelSummary

Show child attributes

idid>= 1

Example

namestring

displayNamestring

urlstring<url>

hoststring<hostname>

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

videoChannelPositioninteger>= 1

Position of the playlist in the channel

500Internal Server Error

search index unavailable

Docs by Sourcey