Moderation

Video Blocks

Operations dealing with blocking videos (removing them from view and preventing interactions).

Block a video

POST

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

Block a video

curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/blacklist' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "reason": "string",
  "unfederate": true,
  "internalNote": "string"
}'

const body = `{
  "reason": "string",
  "unfederate": true,
  "internalNote": "string"
}`;

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

const data = await response.text();

import requests

body = '''{
  "reason": "string",
  "unfederate": true,
  "internalNote": "string"
}'''

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

Request Body

{
  "reason": "string",
  "unfederate": true,
  "internalNote": "string"
}

Body

application/json

reasonstring

Reason for the block (public)

unfederateboolean

Whether to unfederate the video

internalNotestring

Internal note for moderators/admins

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.

Scopes: admin, moderator

Update a video block

PUT

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

Update a video block

curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/42/blacklist' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "reason": "string",
  "internalNote": "string"
}'

const body = `{
  "reason": "string",
  "internalNote": "string"
}`;

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

const data = await response.text();

import requests

body = '''{
  "reason": "string",
  "internalNote": "string"
}'''

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

Request Body

{
  "reason": "string",
  "internalNote": "string"
}

Body

application/json

reasonstring

Reason for the block (displayed publicly)

internalNotestring

Internal note for moderators/admins

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

204No Content

successful operation

404Not Found

block 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

Unblock a video by its id

DELETE

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

Unblock a video by its id

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

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/blacklist', {
  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/blacklist',
    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

block 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

List video blocks

GET

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

List video blocks

curl -X GET 'https://peertube2.cpy.re/api/v1/videos/blacklist?count=15' \
  -H 'Authorization: Bearer YOUR_TOKEN'

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

const data = await response.text();

import requests

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

200

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

Parameters

typeinteger12query

list only blocks that match this type:

1: manual block
2: automatic block that needs review

searchstringquery

plain search that will match with video titles, and more

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

sortstring-idname-duration-views-likes-dislikes-uuid-createdAtquery

Sort blocklists by criteria

Response

200OKobject

successful operation

Response fields application/json

totalinteger

Example

dataArray<VideoBlacklist>

Show child attributes

idid>= 1

Example

reasonstring

Reason for the block (public)

internalNotestring

Internal note for moderators/admins

unfederatedboolean

typeinteger

1: manual block - 2: automatic block by instance policy - 3: automatic block by auto-tag policy

videoVideo

Show child attributes

idid

object id for the video

Show child attributes

id>= 1

Example

uuidUUIDv4

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

Show child attributes

UUIDv4<uuid>

Example

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

shortUUIDshortUUID

Show child attributes

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

shortUUID

Example

2y84q2MQUMWPbiEcxNXMgC

isLiveboolean

liveSchedulesArray<LiveSchedule>

Show child attributes

startAtstring<date-time>

Date when the stream is scheduled to air at

createdAtstring<date-time>

time at which the video object was first drafted

Example

2017-10-01T10:52:46.396Z

publishedAtstring<date-time>

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

Example

2018-10-01T10:52:46.396Z

updatedAtstring<date-time>

last time the video's metadata was modified

Example

2021-05-04T08:01:01.502Z

originallyPublishedAtstring<date-time> | null

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

Example

2010-10-01T10:52:46.396Z

categoryVideoConstantNumber-Category

category in which the video is classified

Show child attributes

idVideoCategorySet

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

Example

labelstring

Example

Science & Technology

licenceVideoConstantNumber-Licence

licence under which the video is distributed

Show child attributes

idVideoLicenceSet

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

Example

labelstring

Example

Attribution - Share Alike

languageVideoConstantString-Language

main language used in the video

Show child attributes

idVideoLanguageSet

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

Example

en

labelstring

Example

English

privacyVideoPrivacyConstant

Show child attributes

idVideoPrivacySet12345

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

labelstring

truncatedDescriptionstring | null

truncated description of the video, written in Markdown.

Example

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

durationinteger<seconds>

duration of the video in seconds

Example

aspectRationumber<float> | null

PeerTube >= 6.1 Aspect ratio of the video stream

Example

1.778

isLocalboolean

namename

title of the video

Example

What is PeerTube?

thumbnailPathstring | nulldeprecated

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

previewPathstring | nulldeprecated

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

thumbnailsArray<Thumbnail>

PeerTube >= 8.1 Array of thumbnails for the video

Show child attributes

fileUrlstring

widthinteger

heightinteger

aspectRatiostring

Example

16:9

embedPathstring

Example

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

viewsinteger

Example

likesinteger

Example

dislikesinteger

Example

commentsinteger

PeerTube >= 7.2 Number of comments on the video

nsfwboolean

nsfwFlagsNSFWFlag

Show child attributes

NSFW flags (can be combined using bitwise or operator)

0 NONE
1 VIOLENT
2 EXPLICIT_SEX

NSFWFlag0124

nsfwSummarystring

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

aiUsageVideoAIUsageConstant

Show child attributes

idVideoAIUsageSet1234

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

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

labelstring

commercialContentVideoCommercialContentConstant

Show child attributes

idVideoCommercialContentSet123

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

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

labelstring

recommendationScopeVideoRecommendationScopeConstant

Show child attributes

idVideoRecommendationScopeSet1234

Videos that can be recommended next to a video:

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

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

labelstring

waitTranscodingboolean | null

stateVideoStateConstant

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

Show child attributes

idid123456789101112131415

The video state:

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

Same fields as data.video.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.video.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

createdAtstring<date-time>

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

Scopes: admin, moderator

Docs by Sourcey