Video

successful operation, when saveAsNewVideo is true. Returns the identifiers of the new video

Response fields application/json

videoobject

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

Example

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

shortUUIDshortUUID

Show child attributes

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

Example

2y84q2MQUMWPbiEcxNXMgC

204No Content

successful operation, when the source video is edited in place

400Bad Request

incorrect parameters

403Forbidden

the user cannot manage this video, or saveAsNewVideo is true on a blocked video and the user cannot manage blocks

404Not Found

video not found

409Conflict

video is already being processed

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.

Duplicate a video

POST

https://peertube2.cpy.re/api/v1/videos/{id}/duplicate

Create a copy of a local video, in the same channel.

The copy of a blocked video (that only moderators can duplicate) is blocked for the same reason.

Duplicate a video

curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/duplicate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string"
}'

const body = `{
  "name": "string"
}`;

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

const data = await response.text();

import requests

body = '''{
  "name": "string"
}'''

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

Request Body

{
  "name": "string"
}

200

{
  "video": {}
}

Body

application/json

namestring

Name of the copy. Defaults to the name of the source video followed by "(Copy)"

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

successful operation. Returns the identifiers of the new video

Response fields application/json

videoobject

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

Example

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

shortUUIDshortUUID

Show child attributes

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

Example

2y84q2MQUMWPbiEcxNXMgC

400Bad Request

incorrect parameters

403Forbidden

the user cannot manage this video, the video is not local, or the video is blocked and the user cannot manage blocks

404Not Found

video not found

409Conflict

video is already being processed

413Payload Too Large

the user video quota is exceeded

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

GET

https://peertube2.cpy.re/api/v1/videos

List videos

curl -X GET 'https://peertube2.cpy.re/api/v1/videos?count=15&skipCount=false'

const response = await fetch('https://peertube2.cpy.re/api/v1/videos?count=15&skipCount=false', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/videos?count=15&skipCount=false')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "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

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

skipCountstringtruefalsefalsequery

if you don't need the total in the response

sortstringname-duration-createdAt-publishedAt-views-likes-comments-trending-hot-bestquery

nsfwstringtruefalsequery

whether to include nsfw videos, if any

nsfwFlagsIncludedNSFWFlag0124query

nsfwFlagsExcludedNSFWFlag0124query

aiUsageOneOfVideoAIUsageSet | Array<VideoAIUsageSet>query

PeerTube >= 9.0 Only list videos with one of these AI usages, declared by video creators. If not provided, the preference of the authenticated user (aiUsagesHidden) is used

isLivebooleanquery

whether or not the video is a live

includeScheduledLivebooleanquery

whether or not include live that are scheduled for later

categoryOneOfVideoCategorySet | Array<VideoCategorySet>query

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

licenceOneOfVideoLicenceSet | Array<VideoLicenceSet>query

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

languageOneOfVideoLanguageSet | Array<VideoLanguageSet>query

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

tagsOneOfstring | Array<string>query

tag(s) of the video

tagsAllOfstring | Array<string>query

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

isLocalbooleanquery

PeerTube >= 4.0 Display only local or remote objects

includeinteger012481632query

Only administrators and moderators can use this parameter

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
16 CAPTIONS
32 VIDEO SOURCE

hasHLSFilesbooleanquery

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFilesbooleanquery

PeerTube >= 6.0 Display only videos that have Web Video files

hoststringquery

Find elements owned by this host

autoTagOneOfstring | Array<string>query

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

stateOneOfid | Array<id>query

PeerTube >= 8.2 Admins and moderators only filter on videos that have one of these states

privacyOneOfVideoPrivacySet12345query

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

excludeAlreadyWatchedbooleanquery

Whether or not to exclude videos that are in the user's video history

searchstringquery

Plain text search, applied to various parts of the model depending on endpoint

Response

successful operation

Response fields application/json

totalinteger

Example

dataArray<Video>

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

Example

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

shortUUIDshortUUID

Show child attributes

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

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

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

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

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

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

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

List recommended videos

GET

https://peertube2.cpy.re/api/v1/recommendations/videos

Return videos recommended next to a reference video (or general recommendations if no reference video is given).

PeerTube decides the recommendation algorithm: it currently lists videos sharing tags with the reference video (excluding videos already watched by the authenticated user), then the latest videos. All returned videos are restricted to the scope, which defaults to the recommendationScope of the reference video.

List recommended videos

curl -X GET 'https://peertube2.cpy.re/api/v1/recommendations/videos?count=10'

const response = await fetch('https://peertube2.cpy.re/api/v1/recommendations/videos?count=10', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/recommendations/videos?count=10')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "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

scopeVideoRecommendationScopeSet1234query

Restrict recommended videos. Defaults to the recommendationScope of the reference video, or to 1 (all videos) if no reference video is given

videoIdid | UUIDv4 | shortUUIDquery

Reference video. Required if scope is 3 or 4

countinteger[1, 30]10query

Number of videos to return

excludeVideoIdsArray<id>query

Videos that must not be recommended (the reference video is always excluded)

nsfwstringtruefalsequery

whether to include nsfw videos, if any

nsfwFlagsIncludedNSFWFlag0124query

nsfwFlagsExcludedNSFWFlag0124query

aiUsageOneOfVideoAIUsageSet | Array<VideoAIUsageSet>query

PeerTube >= 9.0 Only list videos with one of these AI usages, declared by video creators. If not provided, the preference of the authenticated user (aiUsagesHidden) is used

Response

successful operation

Response fields application/json

totalinteger

Example

dataArray<Video>

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

Example

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

shortUUIDshortUUID

Show child attributes

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

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

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

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

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

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

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

400Bad Request

invalid parameters or missing videoId

401Unauthorized

reference video requires authentication or a password

403Forbidden

reference video is not visible by the user or the password is invalid

404Not Found

reference video not found

List available video categories

GET

https://peertube2.cpy.re/api/v1/videos/categories

List available video categories

curl -X GET 'https://peertube2.cpy.re/api/v1/videos/categories'

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/categories', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/videos/categories')
print(response.text)

200

External example: https://peertube2.cpy.re/api/v1/videos/categories

Response

200OKArray<string>

successful operation

Response fields application/json

Array<string>

List available video licences

GET

https://peertube2.cpy.re/api/v1/videos/licences

List available video licences

curl -X GET 'https://peertube2.cpy.re/api/v1/videos/licences'

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/licences', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/videos/licences')
print(response.text)

200

External example: https://peertube2.cpy.re/api/v1/videos/licences

Response

200OKArray<string>

successful operation

Response fields application/json

Array<string>

List available video languages

GET

https://peertube2.cpy.re/api/v1/videos/languages

List available video languages

curl -X GET 'https://peertube2.cpy.re/api/v1/videos/languages'

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/languages', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/videos/languages')
print(response.text)

200

External example: https://peertube2.cpy.re/api/v1/videos/languages

Parameters

scopestringsubtitlequery

PeerTube >= 8.2 Filter languages by scope. Use subtitle to exclude sign languages and other languages that don't make sense for subtitles.

Response

200OKArray<string>

successful operation

Response fields application/json

Array<string>

List available video privacy policies

GET

https://peertube2.cpy.re/api/v1/videos/privacies

List available video privacy policies

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

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

const data = await response.text();

import requests

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

200

External example: https://peertube2.cpy.re/api/v1/videos/privacies

Response

200OKArray<string>

successful operation

Response fields application/json

Array<string>

Get a video

GET

https://peertube2.cpy.re/api/v1/videos/{id}

Get a video

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

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

const data = await response.text();

import requests

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

{
  "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": 42,
    "url": "https://example.com",
    "avatars": [
      {
        "path": "string",
        "fileUrl": "string",
        "width": 0,
        "height": 0,
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
      }
    ],
    "host": "example.com",
    "hostRedundancyAllowed": true,
    "followingCount": 0,
    "followersCount": 0,
    "createdAt": "2024-01-15T09:30:00Z",
    "updatedAt": "2024-01-15T09:30:00Z",
    "displayName": "string",
    "description": "string"
  },
  "channel": {
    "id": 42,
    "url": "https://example.com",
    "avatars": [
      {
        "path": "string",
        "fileUrl": "string",
        "width": 0,
        "height": 0,
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
      }
    ],
    "host": "example.com",
    "hostRedundancyAllowed": true,
    "followingCount": 0,
    "followersCount": 0,
    "createdAt": "2024-01-15T09:30:00Z",
    "updatedAt": "2024-01-15T09:30:00Z",
    "displayName": "Videos of Framasoft",
    "description": "Videos made with <3 by Framasoft",
    "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
    "publicEmail": "user@example.com",
    "isLocal": true,
    "banners": [
      {
        "path": "string",
        "fileUrl": "string",
        "width": 0,
        "height": 0,
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
      }
    ],
    "ownerAccount": {
      "id": 42,
      "url": "https://example.com",
      "avatars": [
        {
          "path": "string",
          "fileUrl": "string",
          "width": 0,
          "height": 0,
          "createdAt": "2024-01-15T09:30:00Z",
          "updatedAt": "2024-01-15T09:30:00Z"
        }
      ],
      "host": "example.com",
      "hostRedundancyAllowed": true,
      "followingCount": 0,
      "followersCount": 0,
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z",
      "displayName": "string",
      "description": "string"
    },
    "videosCount": 0,
    "viewsPerDay": [
      {
        "date": "2024-01-15T09:30:00Z",
        "views": 0
      }
    ],
    "viewsGroupInterval": "day",
    "totalViews": 0
  },
  "userHistory": {
    "currentTime": 0
  },
  "captionLanguages": [
    "fr"
  ],
  "viewers": 0,
  "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,\nbased on free/libre software!*\\r\\n\\r\\n**Animation Produced by:** [LILA](https://libreart.info) - [ZeMarmot Team](https://film.zemarmot.net)\\r\\n\n*Directed by* Aryeom\\r\\n*Assistant* Jehan\\r\\n**Licence**: [CC-By-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)\\r\\n\\r\\n\n**Sponsored by** [Framasoft](https://framasoft.org)\\r\\n\\r\\n**Music**: [Red Step Forward](http://play.dogmazic.net/song.php?song_id=52491) - CC-By Ken Bushima\\r\\n\\r\\n\n**Movie Clip**: [Caminades 3: Llamigos](http://www.caminandes.com/) CC-By Blender Institute\\r\\n\\r\\n**Video sources**: https://gitlab.gnome.org/Jehan/what-is-peertube/\"\n",
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "tags": [
    "flowers",
    "gardening"
  ],
  "commentsPolicy": {
    "id": 1,
    "label": "string"
  },
  "downloadEnabled": true,
  "inputFileUpdatedAt": "2024-01-15T09:30:00Z",
  "trackerUrls": [
    "https://peertube2.cpy.re/tracker/announce",
    "wss://peertube2.cpy.re/tracker/socket"
  ],
  "files": [
    {
      "id": 42,
      "magnetUri": "https://example.com",
      "resolution": {
        "id": 240,
        "label": "240p"
      },
      "size": 0,
      "torrentUrl": "https://example.com",
      "torrentDownloadUrl": "https://example.com",
      "fileUrl": "https://example.com",
      "playlistUrl": "https://example.com",
      "fileDownloadUrl": "https://example.com",
      "fps": 0,
      "width": 0,
      "height": 0,
      "metadataUrl": "https://example.com",
      "hasAudio": true,
      "hasVideo": true,
      "storage": 0
    }
  ],
  "streamingPlaylists": [
    {
      "id": 42,
      "type": 1,
      "playlistUrl": "https://example.com",
      "segmentsSha256Url": "https://example.com",
      "files": [
        {
          "id": 42,
          "magnetUri": "https://example.com",
          "resolution": {
            "id": 240,
            "label": "240p"
          },
          "size": 0,
          "torrentUrl": "https://example.com",
          "torrentDownloadUrl": "https://example.com",
          "fileUrl": "https://example.com",
          "playlistUrl": "https://example.com",
          "fileDownloadUrl": "https://example.com",
          "fps": 0,
          "width": 0,
          "height": 0,
          "metadataUrl": "https://example.com",
          "hasAudio": true,
          "hasVideo": true,
          "storage": 0
        }
      ],
      "redundancies": [
        {
          "baseUrl": "https://example.com"
        }
      ]
    }
  ]
}

{
  "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/video_requires_password",
  "detail": "Please provide a password to access this password protected video",
  "status": 403,
  "code": "video_requires_password"
}

{
  "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/video_requires_password",
  "detail": "Please provide a password to access this password protected video",
  "status": 403,
  "code": "video_requires_password"
}

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

200OKVideo & object

successful operation

Response fields application/json

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

Example

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

shortUUIDshortUUID

Show child attributes

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

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

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

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

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

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

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 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 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

viewersinteger

If the video is a live, you have the amount of current viewers

descriptionstring | null

full 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 free/libre software!*\r\n\r\n**Animation Produced by:** [LILA](https://libreart.info) - [ZeMarmot Team](https://film.zemarmot.net)\r\n
*Directed by* Aryeom\r\n*Assistant* Jehan\r\n**Licence**: [CC-By-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)\r\n\r\n
**Sponsored by** [Framasoft](https://framasoft.org)\r\n\r\n**Music**: [Red Step Forward](http://play.dogmazic.net/song.php?song_id=52491) - CC-By Ken Bushima\r\n\r\n
**Movie Clip**: [Caminades 3: Llamigos](http://www.caminandes.com/) CC-By Blender Institute\r\n\r\n**Video sources**: https://gitlab.gnome.org/Jehan/what-is-peertube/"

supportstring | null

A text tell the audience how to support the video creator

Example

Please support our work on https://soutenir.framasoft.org/en/ <3

channelActor & object

Show child attributes

idid>= 1

Example

Same fields as id

urlstring<url>

nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username

Example

chocobozzz

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>

hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>

updatedAtstring<date-time>

displayNamestring

editable name of the channel, displayed in its representations

Example

Videos of Framasoft

descriptionstring | null

Example

Videos made with <3 by Framasoft

supportstring | null

text shown by default on all videos of this channel, to tell the audience how to support it

Example

Please support our work on https://soutenir.framasoft.org/en/ <3

publicEmailstring<email> | null

Public email visible in podcast RSS feeds

isLocalboolean

updatedAtstring<date-time>

bannersArray<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>

ownerAccountActor & any

Show child attributes

idid>= 1

Example

Same fields as id

urlstring<url>

nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username

Example

chocobozzz

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>

hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>

updatedAtstring<date-time>

userIdid | null

object id for the user tied to this account

Show child attributes

id>= 1

Example

displayNamestring

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

videosCountinteger

only included when withStats is true

viewsPerDayArray<object>

only included when withStats is true. Chronologically ordered, spans the whole statsDays range. Each point aggregates viewsGroupInterval worth of views, starting at date

Show child attributes

datestring<date-time>

viewsinteger

viewsGroupIntervalstringdayweekmonth

bucket size of viewsPerDay, only included when withStats is true

totalViewsinteger

lifetime views of all the channel videos, only included when withStats is true

accountActor & any

Show child attributes

idid>= 1

Example

Same fields as id

urlstring<url>

nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username

Example

chocobozzz

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>

hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>

updatedAtstring<date-time>

userIdid | null

object id for the user tied to this account

Show child attributes

id>= 1

Example

displayNamestring

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

tagsArray<string>

Example

[
  "flowers",
  "gardening"
]

commentsPolicyVideoCommentsPolicyConstant

Show child attributes

idVideoCommentsPolicySet123

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

labelstring

downloadEnabledboolean

inputFileUpdatedAtstring<date-time> | null

Latest input file update. Null if the file has never been replaced since the original upload

trackerUrlsArray<string>

WebTorrent (ws:// or wss://) and BitTorrent (http:// or https://) trackers of the video

Example

[
  "https://peertube2.cpy.re/tracker/announce",
  "wss://peertube2.cpy.re/tracker/socket"
]

filesArray<VideoFile>

Web compatible video files. If Web Video is disabled on the server:

field will be empty
video files will be found in streamingPlaylists[].files field

Show child attributes

idid>= 1

Example

Same fields as id

magnetUristring<uri>

magnet URI allowing to resolve the video via BitTorrent without a metainfo file

resolutionVideoResolutionConstant

resolutions and their labels for the video

Show child attributes

idVideoResolutionSet

Video resolution (0, 240, 360, 720, 1080, 1440 or 2160)

0 is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.

Example

labelstring

Example

240p

sizeinteger

Video file size in bytes

torrentUrlstring<url>

Direct URL of the torrent file

torrentDownloadUrlstring<url>

URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)

fileUrlstring<url>

Direct URL of the video

playlistUrlstring<url>

Playlist URL of the file if it is owned by a playlist

fileDownloadUrlstring<url>

URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)

fpsnumber

Frames per second of the video file

widthnumber

PeerTube >= 6.1 Video stream width

heightnumber

PeerTube >= 6.1 Video stream height

metadataUrlstring<url>

URL dereferencing the output of ffprobe on the file

hasAudioboolean

PeerTube >= 6.2 The file container has an audio stream

hasVideoboolean

PeerTube >= 6.2 The file container has a video stream

storageFileStorage01

The file storage type:

0 File system
1 Object storage

streamingPlaylistsArray<VideoStreamingPlaylists>

HLS playlists/manifest files. If HLS is disabled on the server:

field will be empty
video files will be found in files field

Show child attributes

idid>= 1

Example

Same fields as id

typeinteger1

Playlist type:

1: HLS

playlistUrlstring<url>

segmentsSha256Urlstring<url>

filesArray<VideoFile>

Video files associated to this playlist.

The difference with the root files property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)

Show child attributes

idid>= 1

Example

Same fields as id

magnetUristring<uri>

magnet URI allowing to resolve the video via BitTorrent without a metainfo file

resolutionVideoResolutionConstant

resolutions and their labels for the video

Show child attributes

idVideoResolutionSet

Video resolution (0, 240, 360, 720, 1080, 1440 or 2160)

0 is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.

Example

labelstring

Example

240p

sizeinteger

Video file size in bytes

torrentUrlstring<url>

Direct URL of the torrent file

torrentDownloadUrlstring<url>

URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)

fileUrlstring<url>

Direct URL of the video

playlistUrlstring<url>

Playlist URL of the file if it is owned by a playlist

fileDownloadUrlstring<url>

URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)

fpsnumber

Frames per second of the video file

widthnumber

PeerTube >= 6.1 Video stream width

heightnumber

PeerTube >= 6.1 Video stream height

metadataUrlstring<url>

URL dereferencing the output of ffprobe on the file

hasAudioboolean

PeerTube >= 6.2 The file container has an audio stream

hasVideoboolean

PeerTube >= 6.2 The file container has a video stream

storageFileStorage01

The file storage type:

0 File system
1 Object storage

redundanciesArray<object>

Show child attributes

baseUrlstring<url>

401UnauthorizedServerError

Requires authentication or the video requires a password

Response fields application/json

typestring<uri-reference>

URI identifying the error type. about:blank when the error has no specific type. Otherwise it links to the corresponding section of the Errors documentation; the type name itself is also available in code.

Example

https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/video_requires_password

detailstring

Example

Please provide a password to access this password protected video

statusinteger

Example

codestring

Example

video_requires_password

403ForbiddenServerError

Invalid authentication or the video requires a password

Response fields application/json

typestring<uri-reference>

Example

https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/video_requires_password

detailstring

Example

Please provide a password to access this password protected video

statusinteger

Example

codestring

Example

video_requires_password

Update a video

PUT

https://peertube2.cpy.re/api/v1/videos/{id}

Update a video

curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/42' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'channelId=0' \
  --form-string 'category=15' \
  --form-string 'licence=2' \
  --form-string 'language=en' \
  --form-string 'privacy=1' \
  --form-string 'description=string' \
  --form-string 'waitTranscoding=string' \
  --form-string 'support=Please support our work on https://soutenir.framasoft.org/en/ <3' \
  --form-string 'nsfw=true' \
  --form-string 'nsfwFlags=0' \
  --form-string 'name=string' \
  --form-string 'tags=string' \
  --form-string 'commentsPolicy=1' \
  --form-string 'recommendationScope=1' \
  --form-string 'aiUsage=1' \
  --form-string 'commercialContent=1' \
  --form-string 'downloadEnabled=true' \
  --form-string 'originallyPublishedAt=2024-01-15T09:30:00Z' \
  --form-string 'scheduleUpdate={"privacy":1,"updateAt":"2024-01-15T09:30:00Z"}' \
  --form-string 'videoPasswords=string'

const form = new FormData();
form.append('channelId', '0');
form.append('category', '15');
form.append('licence', '2');
form.append('language', 'en');
form.append('privacy', '1');
form.append('description', 'string');
form.append('waitTranscoding', 'string');
form.append('support', 'Please support our work on https://soutenir.framasoft.org/en/ <3');
form.append('nsfw', 'true');
form.append('nsfwFlags', '0');
form.append('name', 'string');
form.append('tags', 'string');
form.append('commentsPolicy', '1');
form.append('recommendationScope', '1');
form.append('aiUsage', '1');
form.append('commercialContent', '1');
form.append('downloadEnabled', 'true');
form.append('originallyPublishedAt', '2024-01-15T09:30:00Z');
form.append('scheduleUpdate', '{"privacy":1,"updateAt":"2024-01-15T09:30:00Z"}');
form.append('videoPasswords', 'string');
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/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 = [
        ('channelId', (None, '0')),
        ('category', (None, '15')),
        ('licence', (None, '2')),
        ('language', (None, 'en')),
        ('privacy', (None, '1')),
        ('description', (None, 'string')),
        ('waitTranscoding', (None, 'string')),
        ('support', (None, 'Please support our work on https://soutenir.framasoft.org/en/ <3')),
        ('nsfw', (None, 'true')),
        ('nsfwFlags', (None, '0')),
        ('name', (None, 'string')),
        ('tags', (None, 'string')),
        ('commentsPolicy', (None, '1')),
        ('recommendationScope', (None, '1')),
        ('aiUsage', (None, '1')),
        ('commercialContent', (None, '1')),
        ('downloadEnabled', (None, 'true')),
        ('originallyPublishedAt', (None, '2024-01-15T09:30:00Z')),
        ('scheduleUpdate', (None, '{"privacy":1,"updateAt":"2024-01-15T09:30:00Z"}')),
        ('videoPasswords', (None, 'string')),
    ]
    response = requests.request('PUT', 'https://peertube2.cpy.re/api/v1/videos/42', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "channelId": 0,
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "category": 15,
  "licence": 2,
  "language": "en",
  "privacy": 1,
  "description": "string",
  "waitTranscoding": "string",
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "name": "string",
  "tags": [
    "string"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "videoPasswords": [
    "string"
  ]
}

Body

multipart/form-data

multipart/form-dataobject

Encoding

thumbnailfileimage/jpeg

previewfileimage/jpeg

tagsstyle formexplode true

channelIdinteger

New channel of the video. The channel must be owned by the same account as the previous one. Use the "change ownership" endpoints to give a video to a channel owned by another account on the local PeerTube instance.

thumbnailfilestring<binary>

Video thumbnail file

previewfilestring<binary>deprecated

Deprecated in PeerTube v8.1, use thumbnailfile instead

categoryVideoCategorySet

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

Example

licenceVideoLicenceSet

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

Example

languageVideoLanguageSet

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

Example

en

privacyVideoPrivacySet12345

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

descriptionstring

Video description

waitTranscodingstring

Whether or not we wait transcoding before publish the video

supportstring

A text tell the audience how to support the video creator

Example

Please support our work on https://soutenir.framasoft.org/en/ <3

nsfwboolean

Whether or not this video contains sensitive content

nsfwSummaryany

More information about the sensitive content of the video

nsfwFlagsNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

0 NONE
1 VIOLENT
2 EXPLICIT_SEX

namestring

Video name

tagsArray<string>

Video tags (maximum 5 tags each between 2 and 30 characters)

commentsPolicyVideoCommentsPolicySet123

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

recommendationScopeVideoRecommendationScopeSet1234

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

aiUsageVideoAIUsageSet1234

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

commercialContentVideoCommercialContentSet123

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

downloadEnabledboolean

Enable or disable downloading for this video

originallyPublishedAtstring<date-time> | null

Date when the content was originally published

scheduleUpdateVideoScheduledUpdate

Show child attributes

privacyVideoPrivacySet12345

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

updateAtstring<date-time>required

When to update the video

videoPasswordsArray<password>

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

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

DELETE

https://peertube2.cpy.re/api/v1/videos/{id}

Delete a video

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

const response = await fetch('https://peertube2.cpy.re/api/v1/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/videos/42',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

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.

Notify user is watching a video

POST

https://peertube2.cpy.re/api/v1/videos/{id}/views

Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.

Notify user is watching a video

curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/views' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "currentTime": 5,
  "viewEvent": "seek",
  "sessionId": "string",
  "client": "string",
  "operatingSystem": "string"
}'

const body = `{
  "currentTime": 5,
  "viewEvent": "seek",
  "sessionId": "string",
  "client": "string",
  "operatingSystem": "string"
}`;

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

const data = await response.text();

import requests

body = '''{
  "currentTime": 5,
  "viewEvent": "seek",
  "sessionId": "string",
  "client": "string",
  "operatingSystem": "string"
}'''

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

Request Body

{
  "currentTime": 5,
  "viewEvent": "seek",
  "sessionId": "string",
  "client": "string",
  "operatingSystem": "string"
}

Body

application/json

currentTimeinteger<seconds>required

timestamp within the video, in seconds

Example

viewEventstringseek

Event since last viewing call:

seek - If the user seeked the video

sessionIdstring

Optional param to represent the current viewer session. Used by the backend to properly count one view per session per video. PeerTube admin can configure the server to not trust this sessionId parameter but use the request IP address instead to identify a viewer.

clientstring

Client software used to watch the video. For example "Firefox", "PeerTube Approval Android", etc.

deviceVideoStatsUserAgentDevice

Device used to watch the video. For example "desktop", "mobile", "smarttv", etc.

Show child attributes

VideoStatsUserAgentDeviceconsoleembeddedmobilesmarttvtabletwearablexrdesktop

operatingSystemstring

Operating system used to watch the video. For example "Windows", "Ubuntu", etc.

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

204No Content

successful operation

Upload a video

POST

https://peertube2.cpy.re/api/v1/videos/upload

Uses a single request to upload a video.

Upload a video

## DEPENDENCIES: jq
USERNAME="<your_username>"
PASSWORD="<your_password>"
FILE_PATH="<your_file_path>"
CHANNEL_ID="<your_channel_id>"
NAME="<video_name>"
API="https://peertube2.cpy.re/api/v1"

## AUTH
client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
token=$(curl -s "$API/users/token" \
  --data client_id="$client_id" \
  --data client_secret="$client_secret" \
  --data grant_type=password \
  --data username="$USERNAME" \
  --data password="$PASSWORD" \
  | jq -r ".access_token")

## VIDEO UPLOAD
curl -s "$API/videos/upload" \
  -H "Authorization: Bearer $token" \
  --max-time 600 \
  --form videofile=@"$FILE_PATH" \
  --form channelId=$CHANNEL_ID \
  --form name="$NAME"

Request Body

{
  "name": "What is PeerTube?",
  "channelId": 3,
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "**[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)**\n",
  "waitTranscoding": true,
  "generateTranscription": true,
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "tags": [
    "framasoft",
    "peertube"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "videoPasswords": [
    "string"
  ],
  "videofile": "<binary>"
}

200

{
  "video": {}
}

Body

multipart/form-data

multipart/form-dataVideoUploadRequestCommon & object

Encoding

videofile

video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream

thumbnailfileimage/jpeg

previewfileimage/jpeg

namestringrequired

Video name

Example

What is PeerTube?

channelIdinteger>= 1required

Channel id that will contain this video

Example

privacyVideoPrivacySet12345

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

categoryVideoCategorySet

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

Example

licenceVideoLicenceSet

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

Example

languageVideoLanguageSet

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

Example

en

descriptionstring

Video description

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)**

waitTranscodingboolean

Whether or not we wait transcoding before publish the video

generateTranscriptionboolean

PeerTube >= 6.2 If enabled by the admin, automatically generate a subtitle of the video

supportstring

A text tell the audience how to support the video creator

Example

Please support our work on https://soutenir.framasoft.org/en/ <3

nsfwboolean

Whether or not this video contains sensitive content

nsfwSummaryany

More information about the sensitive content of the video

nsfwFlagsNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

0 NONE
1 VIOLENT
2 EXPLICIT_SEX

tagsArray<string>

Video tags (maximum 5 tags each between 2 and 30 characters)

Example

[
  "framasoft",
  "peertube"
]

commentsPolicyVideoCommentsPolicySet123

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

recommendationScopeVideoRecommendationScopeSet1234

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

aiUsageVideoAIUsageSet1234

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

commercialContentVideoCommercialContentSet123

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

downloadEnabledboolean

Enable or disable downloading for this video

originallyPublishedAtstring<date-time>

Date when the content was originally published

scheduleUpdateVideoScheduledUpdate

Show child attributes

privacyVideoPrivacySet12345

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

updateAtstring<date-time>required

When to update the video

thumbnailfilestring<binary>

Video thumbnail file

previewfilestring<binary>deprecated

Deprecated in PeerTube v8.1, use thumbnailfile instead

videoPasswordsArray<password>

videofilestring<binary>required

Video file

Response

successful operation

Response fields application/json

videoobject

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

Example

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

shortUUIDshortUUID

Show child attributes

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

Example

2y84q2MQUMWPbiEcxNXMgC

403Forbidden

video didn't pass upload filter

408Request Timeout

upload has timed out

413Payload Too Large

If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via code:

quota_reached for quota limits whether daily or global

Response headers

X-File-Maximum-Sizestring<Nginx size>header

Maximum file size for the video

415Unsupported Media Type

video type unsupported

422Unprocessable Entity

video unreadable

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.

Initialize the resumable upload of a video

POST

https://peertube2.cpy.re/api/v1/videos/upload-resumable

Uses a resumable protocol to initialize the upload of a video

Initialize the resumable upload of a video

curl -X POST 'https://peertube2.cpy.re/api/v1/videos/upload-resumable' \
  -H 'X-Upload-Content-Length: 2469036' \
  -H 'X-Upload-Content-Type: video/mp4' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "What is PeerTube?",
  "channelId": 3,
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "**[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)**\n",
  "waitTranscoding": true,
  "generateTranscription": true,
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "tags": [
    "framasoft",
    "peertube"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "videoPasswords": [
    "string"
  ],
  "filename": "what_is_peertube.mp4"
}'

const body = `{
  "name": "What is PeerTube?",
  "channelId": 3,
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "**[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)**\\n",
  "waitTranscoding": true,
  "generateTranscription": true,
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "tags": [
    "framasoft",
    "peertube"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "videoPasswords": [
    "string"
  ],
  "filename": "what_is_peertube.mp4"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/upload-resumable', {
  method: 'POST',
  headers: {
    'X-Upload-Content-Length': '2469036',
    'X-Upload-Content-Type': 'video/mp4',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "What is PeerTube?",
  "channelId": 3,
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "**[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)**\\n",
  "waitTranscoding": true,
  "generateTranscription": true,
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "tags": [
    "framasoft",
    "peertube"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "videoPasswords": [
    "string"
  ],
  "filename": "what_is_peertube.mp4"
}'''

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

Request Body

{
  "name": "What is PeerTube?",
  "channelId": 3,
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "**[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)**\n",
  "waitTranscoding": true,
  "generateTranscription": true,
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "tags": [
    "framasoft",
    "peertube"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "videoPasswords": [
    "string"
  ],
  "filename": "what_is_peertube.mp4"
}

Body

application/json

namestringrequired

Video name

Example

What is PeerTube?

channelIdinteger>= 1required

Channel id that will contain this video

Example

privacyVideoPrivacySet12345

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

categoryVideoCategorySet

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

Example

licenceVideoLicenceSet

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

Example

languageVideoLanguageSet

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

Example

en

descriptionstring

Video description

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)**

waitTranscodingboolean

Whether or not we wait transcoding before publish the video

generateTranscriptionboolean

PeerTube >= 6.2 If enabled by the admin, automatically generate a subtitle of the video

supportstring

A text tell the audience how to support the video creator

Example

Please support our work on https://soutenir.framasoft.org/en/ <3

nsfwboolean

Whether or not this video contains sensitive content

nsfwSummaryany

More information about the sensitive content of the video

nsfwFlagsNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

0 NONE
1 VIOLENT
2 EXPLICIT_SEX

tagsArray<string>

Video tags (maximum 5 tags each between 2 and 30 characters)

Example

[
  "framasoft",
  "peertube"
]

commentsPolicyVideoCommentsPolicySet123

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

recommendationScopeVideoRecommendationScopeSet1234

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

aiUsageVideoAIUsageSet1234

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

commercialContentVideoCommercialContentSet123

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

downloadEnabledboolean

Enable or disable downloading for this video

originallyPublishedAtstring<date-time>

Date when the content was originally published

scheduleUpdateVideoScheduledUpdate

Show child attributes

privacyVideoPrivacySet12345

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

updateAtstring<date-time>required

When to update the video

thumbnailfilestring<binary>

Video thumbnail file

previewfilestring<binary>deprecated

Deprecated in PeerTube v8.1, use thumbnailfile instead

videoPasswordsArray<password>

filenamestring<filename>required

Video filename including extension

Example

what_is_peertube.mp4

thumbnailfilestring<binary>

Video thumbnail file

previewfilestring<binary>deprecated

Deprecated in PeerTube v8.1, use thumbnailfile instead

Parameters

X-Upload-Content-Lengthnumberrequiredheader

Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.

X-Upload-Content-Typestring<mimetype>requiredheader

MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.

Response

200OK

file already exists, send a resume request instead

201Created

created

Response headers

Locationstring<url>header

Content-Lengthnumberheader

413Payload Too Large

Disambiguate via code:

max_file_size_reached for the absolute file size limit
quota_reached for quota limits whether daily or global

415Unsupported Media Type

video type unsupported

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.

Send chunk for the resumable upload of a video

PUT

https://peertube2.cpy.re/api/v1/videos/upload-resumable

Uses a resumable protocol to continue, pause or resume the upload of a video

Send chunk for the resumable upload of a video

curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string' \
  -H 'Content-Range: bytes 0-262143/2469036' \
  -H 'Content-Length: 262144' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string', {
  method: 'PUT',
  headers: {
    'Content-Range': 'bytes 0-262143/2469036',
    'Content-Length': '262144',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.put(
    'https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string',
    headers={
        'Content-Range': 'bytes 0-262143/2469036',
        'Content-Length': '262144',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Request Body

"<binary>"

200

{
  "video": {}
}

Body

application/octet-stream

string<binary>

Parameters

upload_idstringrequiredquery

Created session id to proceed with. If you didn't send chunks in the last hour, it is not valid anymore and you need to initialize a new upload.

Content-Rangestringrequiredheader

Specifies the bytes in the file that the request is uploading.

For example, a value of bytes 0-262143/1000000 shows that the request is sending the first 262144 bytes (256 x 1024) in a 2,469,036 byte file.

When the server config client.videos.resumableUpload.minChunkSize (video uploads) or import.users.resumableUpload.minChunkSize (user archive imports) is not 0, every chunk except the last one must be at least that big. It must also be at least 1/10,000 of the file size (the maximum number of object storage multipart upload parts).

Content-Lengthnumberrequiredheader

Size of the chunk that the request is sending.

Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from 1048576 bytes (~1MB) and increases or reduces size depending on connection health.

Response

last chunk received

Response headers

Content-Lengthnumberheader

Response fields application/json

videoobject

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

Example

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

shortUUIDshortUUID

Show child attributes

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

Example

2y84q2MQUMWPbiEcxNXMgC

308Permanent Redirect

resume incomplete

Response headers

Content-Lengthnumberheader

400Bad Request

chunk is smaller than client.videos.resumableUpload.minChunkSize of the server config or 1/10,000 of the file size (and is not the last one)

403Forbidden

video didn't pass upload filter

404Not Found

upload not found

409Conflict

chunk doesn't match range

422Unprocessable Entity

video unreadable

429Too Many Requests

too many concurrent requests

503Service Unavailable

upload is already being processed

Response headers

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.

Cancel the resumable upload of a video, deleting any data uploaded so far

DELETE

https://peertube2.cpy.re/api/v1/videos/upload-resumable

Uses a resumable protocol to cancel the upload of a video

Cancel the resumable upload of a video, deleting any data uploaded so far

curl -X DELETE 'https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string' \
  -H 'Content-Length: 0' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string', {
  method: 'DELETE',
  headers: {
    'Content-Length': '0',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string',
    headers={
        'Content-Length': '0',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

upload_idstringrequiredquery

Created session id to proceed with. If you didn't send chunks in the last hour, it is not valid anymore and you need to initialize a new upload.

Content-Lengthnumberrequiredheader

Response

204No Content

upload cancelled

Response headers

Content-Lengthnumberheader

404Not Found

upload not found

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.

Create a live

POST

https://peertube2.cpy.re/api/v1/videos/live

Create a live

curl -X POST 'https://peertube2.cpy.re/api/v1/videos/live' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'channelId=0' \
  --form-string 'saveReplay=true' \
  --form-string 'replaySettings={"privacy":1}' \
  --form-string 'permanentLive=true' \
  --form-string 'privacy=1' \
  --form-string 'category=15' \
  --form-string 'licence=2' \
  --form-string 'language=en' \
  --form-string 'description=string' \
  --form-string 'support=Please support our work on https://soutenir.framasoft.org/en/ <3' \
  --form-string 'nsfw=true' \
  --form-string 'nsfwFlags=0' \
  --form-string 'name=string' \
  --form-string 'tags=string' \
  --form-string 'commentsPolicy=1' \
  --form-string 'recommendationScope=1' \
  --form-string 'aiUsage=1' \
  --form-string 'commercialContent=1' \
  --form-string 'downloadEnabled=true' \
  --form-string 'schedules={"startAt":"2024-01-15T09:30:00Z"}'

const form = new FormData();
form.append('channelId', '0');
form.append('saveReplay', 'true');
form.append('replaySettings', '{"privacy":1}');
form.append('permanentLive', 'true');
form.append('privacy', '1');
form.append('category', '15');
form.append('licence', '2');
form.append('language', 'en');
form.append('description', 'string');
form.append('support', 'Please support our work on https://soutenir.framasoft.org/en/ <3');
form.append('nsfw', 'true');
form.append('nsfwFlags', '0');
form.append('name', 'string');
form.append('tags', 'string');
form.append('commentsPolicy', '1');
form.append('recommendationScope', '1');
form.append('aiUsage', '1');
form.append('commercialContent', '1');
form.append('downloadEnabled', 'true');
form.append('schedules', '{"startAt":"2024-01-15T09:30:00Z"}');
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/live', {
  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 = [
        ('channelId', (None, '0')),
        ('saveReplay', (None, 'true')),
        ('replaySettings', (None, '{"privacy":1}')),
        ('permanentLive', (None, 'true')),
        ('privacy', (None, '1')),
        ('category', (None, '15')),
        ('licence', (None, '2')),
        ('language', (None, 'en')),
        ('description', (None, 'string')),
        ('support', (None, 'Please support our work on https://soutenir.framasoft.org/en/ <3')),
        ('nsfw', (None, 'true')),
        ('nsfwFlags', (None, '0')),
        ('name', (None, 'string')),
        ('tags', (None, 'string')),
        ('commentsPolicy', (None, '1')),
        ('recommendationScope', (None, '1')),
        ('aiUsage', (None, '1')),
        ('commercialContent', (None, '1')),
        ('downloadEnabled', (None, 'true')),
        ('schedules', (None, '{"startAt":"2024-01-15T09:30:00Z"}')),
    ]
    response = requests.request('POST', 'https://peertube2.cpy.re/api/v1/videos/live', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "channelId": 0,
  "saveReplay": true,
  "replaySettings": {
    "privacy": 1
  },
  "permanentLive": true,
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "string",
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "name": "string",
  "tags": [
    "string"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "schedules": [
    {
      "startAt": "2024-01-15T09:30:00Z"
    }
  ]
}

200

{
  "video": {}
}

Body

multipart/form-data

multipart/form-dataobject

Encoding

thumbnailfileimage/jpeg

previewfileimage/jpeg

channelIdintegerrequired

Channel id that will contain this live video

saveReplayboolean

replaySettingsLiveVideoReplaySettings

Show child attributes

privacyVideoPrivacySet12345

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

permanentLiveboolean

User can stream multiple times in a permanent live

latencyModeLiveVideoLatencyMode

User can select live latency mode if enabled by the instance

Show child attributes

The live latency mode (Default = 1, High latency = 2, Small Latency = 3)

LiveVideoLatencyMode123

thumbnailfilestring<binary>

Live video/replay thumbnail file

previewfilestring<binary>deprecated

Deprecated in PeerTube v8.1, use thumbnailfile instead

privacyVideoPrivacySet12345

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

categoryVideoCategorySet

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

Example

licenceVideoLicenceSet

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

Example

languageVideoLanguageSet

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

Example

en

descriptionstring

Live video/replay description

supportstring

A text tell the audience how to support the creator

Example

Please support our work on https://soutenir.framasoft.org/en/ <3

nsfwboolean

Whether or not this live video/replay contains sensitive content

nsfwSummaryany

More information about the sensitive content of the video

nsfwFlagsNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

0 NONE
1 VIOLENT
2 EXPLICIT_SEX

namestringrequired

Live video/replay name

tagsArray<string>

Live video/replay tags (maximum 5 tags each between 2 and 30 characters)

commentsPolicyVideoCommentsPolicySet123

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

recommendationScopeVideoRecommendationScopeSet1234

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

aiUsageVideoAIUsageSet1234

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

commercialContentVideoCommercialContentSet123

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

downloadEnabledboolean

Enable or disable downloading for the replay of this live video

schedulesArray<LiveSchedule>

Show child attributes

startAtstring<date-time>

Date when the stream is scheduled to air at

Response

successful operation

Response fields application/json

videoobject

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

Example

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

shortUUIDshortUUID

Show child attributes

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

Example

2y84q2MQUMWPbiEcxNXMgC

400Bad Request

Disambiguate via code:

default type for a validation error
live_conflicting_permanent_and_save_replay for conflicting parameters set

403Forbidden

Disambiguate via code:

live_not_enabled for a disabled live feature
live_not_allowing_replay for a disabled replay feature
max_instance_lives_limit_reached for the absolute concurrent live limit
max_user_lives_limit_reached for the user concurrent live limit

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 information about a live

GET

https://peertube2.cpy.re/api/v1/videos/live/{id}

Get information about a live

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

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

const data = await response.text();

import requests

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

200

{
  "rtmpUrl": "string",
  "rtmpsUrl": "string",
  "streamKey": "string",
  "saveReplay": true,
  "replaySettings": {
    "privacy": 1
  },
  "permanentLive": true,
  "schedules": [
    {
      "startAt": "2024-01-15T09:30:00Z"
    }
  ]
}

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

200OKLiveVideoResponse

successful operation

Response fields application/json

rtmpUrlstring

Included in the response if an appropriate token is provided

rtmpsUrlstring

Included in the response if an appropriate token is provided

streamKeystring

RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided

saveReplayboolean

replaySettingsLiveVideoReplaySettings

Show child attributes

privacyVideoPrivacySet12345

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

permanentLiveboolean

User can stream multiple times in a permanent live

latencyModeLiveVideoLatencyMode

User can select live latency mode if enabled by the instance

Show child attributes

The live latency mode (Default = 1, High latency = 2, Small Latency = 3)

LiveVideoLatencyMode123

schedulesArray<LiveSchedule>

Show child attributes

startAtstring<date-time>

Date when the stream is scheduled to air at

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 information about a live

PUT

https://peertube2.cpy.re/api/v1/videos/live/{id}

Update information about a live

curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/live/42' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "saveReplay": true,
  "replaySettings": {
    "privacy": 1
  },
  "permanentLive": true,
  "schedules": [
    {
      "startAt": "2024-01-15T09:30:00Z"
    }
  ]
}'

const body = `{
  "saveReplay": true,
  "replaySettings": {
    "privacy": 1
  },
  "permanentLive": true,
  "schedules": [
    {
      "startAt": "2024-01-15T09:30:00Z"
    }
  ]
}`;

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

const data = await response.text();

import requests

body = '''{
  "saveReplay": true,
  "replaySettings": {
    "privacy": 1
  },
  "permanentLive": true,
  "schedules": [
    {
      "startAt": "2024-01-15T09:30:00Z"
    }
  ]
}'''

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

Request Body

{
  "saveReplay": true,
  "replaySettings": {
    "privacy": 1
  },
  "permanentLive": true,
  "schedules": [
    {
      "startAt": "2024-01-15T09:30:00Z"
    }
  ]
}

Body

application/json

saveReplayboolean

replaySettingsLiveVideoReplaySettings

Show child attributes

privacyVideoPrivacySet12345

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

permanentLiveboolean

User can stream multiple times in a permanent live

latencyModeLiveVideoLatencyMode

User can select live latency mode if enabled by the instance

Show child attributes

The live latency mode (Default = 1, High latency = 2, Small Latency = 3)

LiveVideoLatencyMode123

schedulesArray<LiveSchedule>

Show child attributes

startAtstring<date-time>

Date when the stream is scheduled to air at

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

204No Content

successful operation

400Bad Request

bad parameters or trying to update a live that has already started

403Forbidden

trying to save replay of the live but saving replay is not enabled on the instance

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 video source file metadata

GET

https://peertube2.cpy.re/api/v1/videos/{id}/source

Get metadata and download link of original video file

Get video source file metadata

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

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

const data = await response.text();

import requests

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

200

{
  "inputFilename": "string",
  "fileDownloadUrl": "string",
  "resolution": {
    "id": 240,
    "label": "240p"
  },
  "size": 0,
  "fps": 0,
  "width": 0,
  "height": 0,
  "createdAt": "2024-01-15T09:30:00Z"
}

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

200OKVideoSource

successful operation

Response fields application/json

inputFilenamestring

Uploaded/imported filename

fileDownloadUrlstring

PeerTube >= 6.1 If enabled by the admin, the video source file is kept on the server and can be downloaded by the owner

resolutionVideoResolutionConstant

PeerTube >= 6.1

Show child attributes

resolutions and their labels for the video

idVideoResolutionSet

Video resolution (0, 240, 360, 720, 1080, 1440 or 2160)

0 is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.

Example

labelstring

Example

240p

sizeinteger

PeerTube >= 6.1 Video file size in bytes

fpsnumber

PeerTube >= 6.1 Frames per second of the video file

widthinteger

PeerTube >= 6.1 Video stream width

heightinteger

PeerTube >= 6.1 Video stream height

createdAtstring<date-time>

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 video source file

DELETE

https://peertube2.cpy.re/api/v1/videos/{id}/source/file

Delete video source file

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

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

const data = await response.text();

import requests

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

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

204No Content

successful operation

404Not Found

video source not found

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.

Scopes: admin, moderator

Initialize the resumable replacement of a video

POST

https://peertube2.cpy.re/api/v1/videos/{id}/source/replace-resumable

PeerTube >= 6.0 Uses a resumable protocol to initialize the replacement of a video

Initialize the resumable replacement of a video

curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable' \
  -H 'X-Upload-Content-Length: 2469036' \
  -H 'X-Upload-Content-Type: video/mp4' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "filename": "what_is_peertube.mp4"
}'

const body = `{
  "filename": "what_is_peertube.mp4"
}`;

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

const data = await response.text();

import requests

body = '''{
  "filename": "what_is_peertube.mp4"
}'''

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

Request Body

{
  "filename": "what_is_peertube.mp4"
}

Body

application/json

filenamestring<filename>

Video filename including extension

Example

what_is_peertube.mp4

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

X-Upload-Content-Lengthnumberrequiredheader

Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.

X-Upload-Content-Typestring<mimetype>requiredheader

MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.

Response

200OK

file already exists, send a resume request instead

201Created

created

Response headers

Locationstring<url>header

Content-Lengthnumberheader

413Payload Too Large

Disambiguate via code:

max_file_size_reached for the absolute file size limit
quota_reached for quota limits whether daily or global

415Unsupported Media Type

video type unsupported

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.

Send chunk for the resumable replacement of a video

PUT

https://peertube2.cpy.re/api/v1/videos/{id}/source/replace-resumable

PeerTube >= 6.0 Uses a resumable protocol to continue, pause or resume the replacement of a video

Send chunk for the resumable replacement of a video

curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string' \
  -H 'Content-Range: bytes 0-262143/2469036' \
  -H 'Content-Length: 262144' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string', {
  method: 'PUT',
  headers: {
    'Content-Range': 'bytes 0-262143/2469036',
    'Content-Length': '262144',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.put(
    'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string',
    headers={
        'Content-Range': 'bytes 0-262143/2469036',
        'Content-Length': '262144',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Request Body

"<binary>"

Body

application/octet-stream

string<binary>

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

upload_idstringrequiredquery

Created session id to proceed with. If you didn't send chunks in the last hour, it is not valid anymore and you need to initialize a new upload.

Content-Rangestringrequiredheader

Specifies the bytes in the file that the request is uploading.

For example, a value of bytes 0-262143/1000000 shows that the request is sending the first 262144 bytes (256 x 1024) in a 2,469,036 byte file.

Content-Lengthnumberrequiredheader

Size of the chunk that the request is sending.

Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from 1048576 bytes (~1MB) and increases or reduces size depending on connection health.

Response

204No Content

last chunk received: successful operation

308Permanent Redirect

resume incomplete

Response headers

Content-Lengthnumberheader

400Bad Request

chunk is smaller than client.videos.resumableUpload.minChunkSize of the server config or 1/10,000 of the file size (and is not the last one)

403Forbidden

video didn't pass file replacement filter

404Not Found

replace upload not found

409Conflict

chunk doesn't match range

422Unprocessable Entity

video unreadable

429Too Many Requests

too many concurrent requests

503Service Unavailable

upload is already being processed

Response headers

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.

Cancel the resumable replacement of a video

DELETE

https://peertube2.cpy.re/api/v1/videos/{id}/source/replace-resumable

PeerTube >= 6.0 Uses a resumable protocol to cancel the replacement of a video

Cancel the resumable replacement of a video

curl -X DELETE 'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string' \
  -H 'Content-Length: 0' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string', {
  method: 'DELETE',
  headers: {
    'Content-Length': '0',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string',
    headers={
        'Content-Length': '0',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

upload_idstringrequiredquery

Created session id to proceed with. If you didn't send chunks in the last hour, it is not valid anymore and you need to initialize a new upload.

Content-Lengthnumberrequiredheader

Response

204No Content

source file replacement cancelled

Response headers

Content-Lengthnumberheader

404Not Found

source file replacement not found

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 storyboards of a video

GET

https://peertube2.cpy.re/api/v1/videos/{id}/storyboards

PeerTube >= 6.0

List storyboards of a video

curl -X GET 'https://peertube2.cpy.re/api/v1/videos/42/storyboards'

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

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/videos/42/storyboards')
print(response.text)

200

{
  "storyboards": [
    {
      "storyboardPath": "string",
      "fileUrl": "string",
      "totalHeight": 0,
      "totalWidth": 0,
      "spriteHeight": 0,
      "spriteWidth": 0,
      "spriteDuration": 0
    }
  ]
}

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

200OKobject

successful operation

Response fields application/json

storyboardsArray<Storyboard>

Show child attributes

storyboardPathstring | 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

totalHeightinteger

totalWidthinteger

spriteHeightinteger

spriteWidthinteger

spriteDurationinteger

List videos of a video channel

GET

https://peertube2.cpy.re/api/v1/video-channels/{channelHandle}/videos

List videos of a video channel

curl -X GET 'https://peertube2.cpy.re/api/v1/video-channels/my_username%20%7C%20my_username%40example.com/videos?count=15&skipCount=false'

const response = await fetch('https://peertube2.cpy.re/api/v1/video-channels/my_username%20%7C%20my_username%40example.com/videos?count=15&skipCount=false', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/video-channels/my_username%20%7C%20my_username%40example.com/videos?count=15&skipCount=false')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "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

channelHandlestringrequiredpath

The video channel handle

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

skipCountstringtruefalsefalsequery

if you don't need the total in the response

sortstringname-duration-createdAt-publishedAt-views-likes-comments-trending-hot-bestquery

nsfwstringtruefalsequery

whether to include nsfw videos, if any

nsfwFlagsIncludedNSFWFlag0124query

nsfwFlagsExcludedNSFWFlag0124query

aiUsageOneOfVideoAIUsageSet | Array<VideoAIUsageSet>query

PeerTube >= 9.0 Only list videos with one of these AI usages, declared by video creators. If not provided, the preference of the authenticated user (aiUsagesHidden) is used

isLivebooleanquery

whether or not the video is a live

includeScheduledLivebooleanquery

whether or not include live that are scheduled for later

categoryOneOfVideoCategorySet | Array<VideoCategorySet>query

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

licenceOneOfVideoLicenceSet | Array<VideoLicenceSet>query

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

languageOneOfVideoLanguageSet | Array<VideoLanguageSet>query

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

tagsOneOfstring | Array<string>query

tag(s) of the video

tagsAllOfstring | Array<string>query

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

isLocalbooleanquery

PeerTube >= 4.0 Display only local or remote objects

includeinteger012481632query

Only administrators and moderators can use this parameter

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
16 CAPTIONS
32 VIDEO SOURCE

hasHLSFilesbooleanquery

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFilesbooleanquery

PeerTube >= 6.0 Display only videos that have Web Video files

hoststringquery

Find elements owned by this host

autoTagOneOfstring | Array<string>query

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

stateOneOfid | Array<id>query

PeerTube >= 8.2 Admins and moderators only filter on videos that have one of these states

privacyOneOfVideoPrivacySet12345query

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

excludeAlreadyWatchedbooleanquery

Whether or not to exclude videos that are in the user's video history

searchstringquery

Plain text search, applied to various parts of the model depending on endpoint

Response

successful operation

Response fields application/json

totalinteger

Example

dataArray<Video>

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

Example

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

shortUUIDshortUUID

Show child attributes

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

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

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

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

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

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

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

Search videos

GET

https://peertube2.cpy.re/api/v1/search/videos

Search videos

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

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

const data = await response.text();

import requests

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

200

{
  "total": 1,
  "data": [
    {
      "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

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 video information and interact with it.

uuidsanyquery

Find elements with specific UUIDs

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

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

skipCountstringtruefalsefalsequery

if you don't need the total in the response

sortstringname-duration-createdAt-publishedAt-views-likes-comments-trending-hot-bestquery

nsfwstringtruefalsequery

whether to include nsfw videos, if any

nsfwFlagsIncludedNSFWFlag0124query

nsfwFlagsExcludedNSFWFlag0124query

aiUsageOneOfVideoAIUsageSet | Array<VideoAIUsageSet>query

PeerTube >= 9.0 Only list videos with one of these AI usages, declared by video creators. If not provided, the preference of the authenticated user (aiUsagesHidden) is used

isLivebooleanquery

whether or not the video is a live

includeScheduledLivebooleanquery

whether or not include live that are scheduled for later

categoryOneOfVideoCategorySet | Array<VideoCategorySet>query

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

licenceOneOfVideoLicenceSet | Array<VideoLicenceSet>query

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

languageOneOfVideoLanguageSet | Array<VideoLanguageSet>query

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

tagsOneOfstring | Array<string>query

tag(s) of the video

tagsAllOfstring | Array<string>query

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

isLocalbooleanquery

PeerTube >= 4.0 Display only local or remote objects

includeinteger012481632query

Only administrators and moderators can use this parameter

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
16 CAPTIONS
32 VIDEO SOURCE

hasHLSFilesbooleanquery

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFilesbooleanquery

PeerTube >= 6.0 Display only videos that have Web Video files

hoststringquery

Find elements owned by this host

autoTagOneOfstring | Array<string>query

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

stateOneOfid | Array<id>query

PeerTube >= 8.2 Admins and moderators only filter on videos that have one of these states

privacyOneOfVideoPrivacySet12345query

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

excludeAlreadyWatchedbooleanquery

Whether or not to exclude videos that are in the user's video history

startDatestring<date-time>query

Get videos that are published after this date

endDatestring<date-time>query

Get videos that are published before this date

originallyPublishedStartDatestring<date-time>query

Get videos that are originally published after this date

originallyPublishedEndDatestring<date-time>query

Get videos that are originally published before this date

durationMinintegerquery

Get videos that have this minimum duration

durationMaxintegerquery

Get videos that have this maximum duration

Response

successful operation

Response fields application/json

totalinteger

Example

dataArray<Video>

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

Example

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

shortUUIDshortUUID

Show child attributes

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

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

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

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

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

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