Sign in

v1

latestOpenAPI 3.0.0AGPLv3.02026-07-14186117194.3 KB
Video

List videos

get/api/v1/videos

Query parameters

integer

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

OR
VideoCategorySet[]
Example:15

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

isLiveboolean

whether or not the video is a live

string
OR
string[]

tag(s) of the video

string
OR
string[]

tag(s) of the video, where all should be present in the video

integer

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

OR
VideoLicenceSet[]
Example:2

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

string

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

OR
VideoLanguageSet[]
Example:en

language id of the video (see /videos/languages). Use _unknown to filter on videos that don't have a video language

nsfw'true' | 'false'

whether to include nsfw videos, if any

isLocalboolean

PeerTube >= 4.0 Display only local or remote videos

include0 | 1 | 2 | 4 | 8

PeerTube >= 4.0 Include additional videos in results (can be combined using bitwise or operator)

  • 0 NONE
  • 1 NOT_PUBLISHED_STATE
  • 2 BLACKLISTED
  • 4 BLOCKED_OWNER
  • 8 FILES
privacyOneOf1 | 2 | 3 | 4

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

PeerTube >= 4.0 Display only videos in this specific privacy/privacies

hasHLSFilesboolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebtorrentFilesboolean

PeerTube >= 4.0 Display only videos that have WebTorrent files

skipCount'true' | 'false'

if you don't need the total in the response

startinteger

Offset used to paginate results

countinteger

Number of items to return

sort'name' | '-duration' | '-createdAt' | '-publishedAt' | '-views' | '-likes' | '-trending' | '-hot' | '-best'

Sort videos by criteria (prefixing with - means DESC order):

  • hot - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
  • best - Same than hot, but also takes into account user video history
  • trending - Sort videos by recent views ("recent" is defined by the admin)
  • views - Sort videos using their views counter
  • publishedAt - Sort by video publication date (when it became publicly available)

Response

successful operation

totalinteger

Example response

{
  "data": [
    {
      "category": {
        "id": 15,
        "label": "Science & Technology"
      },
      "channel": {
        "id": 42
      },
      "createdAt": "2017-10-01T10:52:46.396Z",
      "description": "**[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",
      "dislikes": 7,
      "duration": 1419,
      "embedPath": "/videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee",
      "id": 42,
      "language": {
        "id": "en",
        "label": "English"
      },
      "licence": {
        "id": 2,
        "label": "Attribution - Share Alike"
      },
      "likes": 42,
      "name": "What is PeerTube?",
      "originallyPublishedAt": "2010-10-01T10:52:46.396Z",
      "previewPath": "/lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg",
      "publishedAt": "2018-10-01T10:52:46.396Z",
      "shortUUID": "2y84q2MQUMWPbiEcxNXMgC",
      "thumbnailPath": "/static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg",
      "updatedAt": "2021-05-04T08:01:01.502Z",
      "uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
      "views": 1337
    }
  ],
  "total": 1
}