Accounts

My User

Operations related to your own User, when logged-in.

Get my user information

GET
https://peertube2.cpy.re/api/v1/users/me

Response

200OKArray<User>

successful operation

Response fields application/json
Array<User>
Show child attributes
idid>= 1
Example
42
usernameusername

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

Example
chocobozzz
emailemail<email>

The user email

emailVerifiedboolean

Has the user confirmed their email address?

nsfwPolicyNSFWPolicydisplaywarndo_not_list
nsfwFlagsDisplayedNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
nsfwFlagsHiddenNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
nsfwFlagsWarnedNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
nsfwFlagsBlurredNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
aiUsagesHiddenArray<VideoAIUsageSet>1234

PeerTube >= 9.0 Videos with these AI usages are hidden from video lists

adminFlagsUserAdminFlags01

Admin flags for the user (None = 0, Bypass video blocklist = 1)

Example
1
autoPlayNextVideoboolean

Automatically start playing the upcoming video after the currently playing video

autoPlayNextVideoPlaylistboolean

Automatically start playing the video on the playlist after the currently playing video

autoPlayVideoboolean

Automatically start playing the video on the watch page

p2pEnabledboolean

whether to enable P2P in the player or not

videosHistoryEnabledboolean

whether to keep track of watched history or not

videoLanguagesArray<string>

list of languages to filter videos down to

videoCategoriesArray<integer> | null

list of categories to filter videos down to (null means all categories)

videoLivestringtruefalseboth

filter videos down to lives (true), VODs (false) or display both

languagestring

default language for this user

videoQuotainteger

The user video quota in bytes

Example
-1
videoQuotaDailyinteger

The user daily video quota in bytes

Example
-1
roleobject
Show child attributes
idUserRole012

The user role (Admin = 0, Moderator = 1, User = 2)

Example
2
labelstringUserModeratorAdministrator
themestring

Theme enabled by this user

accountActor & any
Show child attributes
idid>= 1
Example
42
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
42
displayNamestring

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

notificationSettingsUserNotificationSettings
Show child attributes
abuseAsModeratorNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
videoAutoBlacklistAsModeratorNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newUserRegistrationNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newVideoFromSubscriptionNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
blacklistOnMyVideoNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoPublishedNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoImportFinishedNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
commentMentionNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newCommentOnMyVideoNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newFollowNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newInstanceFollowerNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
autoInstanceFollowingNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
abuseStateChangeNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
abuseNewMessageNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newPeerTubeVersionNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newPluginVersionNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoStudioEditionFinishedNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoTranscriptionGeneratedNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
videoChannelsArray<VideoChannel>
Show child attributes
idid>= 1
Example
42

Same fields as account.userId

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
42

Same fields as account.userId

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

blockedboolean
blockedReasonstring
noInstanceConfigWarningModalboolean
noAccountSetupWarningModalboolean
noWelcomeModalboolean
createdAtstring
pluginAuthstring

Auth plugin to use to authenticate the user

lastLoginDatestring<date-time>
twoFactorEnabledboolean

Whether the user has enabled two-factor authentication or not

newFeaturesInfoReadnumber

New features information the user has read

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

Update my user information

PUT
https://peertube2.cpy.re/api/v1/users/me

Body

application/json
currentPasswordpassword<password>
emailemail

new email used for login and service communications

Show child attributes

The user email

email<email>
displayNamestring

new name of the user in its representations

nsfwPolicystringtruefalseboth

new NSFW display policy

nsfwFlagsDisplayedNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
nsfwFlagsHiddenNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
nsfwFlagsWarnedNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
nsfwFlagsBlurredNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
aiUsagesHiddenArray<VideoAIUsageSet>1234

PeerTube >= 9.0 Videos with these AI usages are hidden from video lists

p2pEnabledboolean

whether to enable P2P in the player or not

autoPlayVideoboolean

new preference regarding playing videos automatically

autoPlayNextVideoboolean

new preference regarding playing following videos automatically

autoPlayNextVideoPlaylistboolean

new preference regarding playing following playlist videos automatically

videosHistoryEnabledboolean

whether to keep track of watched history or not

videoLanguagesArray<string>

list of languages to filter videos down to

videoCategoriesArray<integer> | null

list of categories to filter videos down to (null means all categories)

videoLivestringtruefalseboth

filter videos down to lives (true), VODs (false) or display both

languagestring

default language for this user

themestring
noInstanceConfigWarningModalboolean
noAccountSetupWarningModalboolean
noWelcomeModalboolean

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

Delete my account

DELETE
https://peertube2.cpy.re/api/v1/users/me

Delete the authenticated user's account and all associated data

Response

204No Content

successful operation - account deleted

400Bad Request

invalid request parameters

401Unauthorized

authentication required

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

Get video imports of my user

GET
https://peertube2.cpy.re/api/v1/users/me/videos/imports

Parameters

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

sortstringquery

Sort column

includeCollaborationsbooleanquery

PeerTube >= 8.0 Include objects from collaborated channels

videoIdintegerquery

Filter on import video ID

targetUrlstringquery

Filter on import target URL

videoChannelSyncIdnumberquery

Filter on imports created by a specific channel synchronization

searchstringquery

Search in video names

stateOneOfArray<id>123456query

Filter on import state

Response

200OKVideoImportsList

successful operation

Response fields application/json
totalinteger
Example
1
dataArray<VideoImport>
Show child attributes
idid>= 1
Example
42
targetUrltargetUrl<url>

remote URL where to find the import's source video

Example
https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
magnetUrimagnetUri<uri>

magnet URI allowing to resolve the import's source video

torrentfiletorrentfile<binary>

Torrent file containing only the video file

torrentNamestring
stateVideoImportStateConstant
Show child attributes
idid123456

The video import state (Pending = 1, Success = 2, Failed = 3, Rejected = 4, Cancelled = 5, Processing = 6)

labelstring
Example
Pending
errorstring
createdAtstring<date-time>
updatedAtstring<date-time>
videoVideo | null
Show child attributes
idid

object id for the video

Show child attributes
id>= 1
Example
42
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
15
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
2
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

privacy policy used to distribute the video

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
1419
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
1337
likesinteger
Example
42
dislikesinteger
Example
7
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
42

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

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

Get my user used quota

GET
https://peertube2.cpy.re/api/v1/users/me/video-quota-used

Response

200OKobject

successful operation

Response fields application/json
videoQuotaUsednumber

The user video quota used so far in bytes

Example
16810141515
videoQuotaUsedDailynumber

The user video quota used today in bytes

Example
1681014151

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

Get rate of my user for a video

GET
https://peertube2.cpy.re/api/v1/users/me/videos/{videoIdOrUUID}/rating

Parameters

videoIdOrUUIDid | UUIDv4 | shortUUIDrequiredpath

Video id or UUID

Response

200OKGetMeVideoRating

successful operation

Response fields application/json
idid>= 1required
Example
42
ratingstringlikedislikenonerequired

Rating of the video

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

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

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

List videos of my user

GET
https://peertube2.cpy.re/api/v1/users/me/videos

Parameters

channelNameOneOfstring | Array<string>query

PeerTube >= 7.2 Filter on videos that are published by a channel with one of these names

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

includeCollaborationsbooleanquery

PeerTube >= 8.0 Include objects from collaborated channels

Response

200OKVideoListResponse

successful operation

Response fields application/json
totalinteger
Example
1
dataArray<Video>
Show child attributes
idid

object id for the video

Show child attributes
id>= 1
Example
42
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
15
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
2
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

privacy policy used to distribute the video

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
1419
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
1337
likesinteger
Example
42
dislikesinteger
Example
7
commentsinteger

PeerTube >= 7.2 Number of comments on the video

nsfwboolean
nsfwFlagsNSFWFlag
Show child attributes

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
NSFWFlag0124
nsfwSummarystring

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

aiUsageVideoAIUsageConstant
Show child attributes
idVideoAIUsageSet1234

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

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

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

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

Videos that can be recommended next to a video:

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

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

labelstring
waitTranscodingboolean | null
stateVideoStateConstant

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

Show child attributes
idid123456789101112131415

The video state:

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

Same fields as data.id

labelstring
scheduledUpdateVideoScheduledUpdate | null
Show child attributes
privacyVideoPrivacySet12345

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

updateAtstring<date-time>required

When to update the video

blacklistedboolean | null
blacklistedReasonstring | null
accountAccountSummary
Show child attributes
idinteger
namestring
displayNamestring
urlstring<url>
hoststring<hostname>
avatarsArray<ActorImage>
Show child attributes
pathstring | nulldeprecated

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

fileUrlstring

PeerTube >= 7.1

widthinteger
heightinteger

PeerTube >= 7.3

createdAtstring<date-time>
updatedAtstring<date-time>
channelVideoChannelSummary
Show child attributes
idid>= 1
Example
42

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

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

Mark feature info as read

POST
https://peertube2.cpy.re/api/v1/users/me/new-feature-info/read

**PeerTube >= v8.0.0

Body

application/json
featureNewFeatureInfoType1required

Represent a new feature that can be displayed to inform users. One of the following values:

  • 1 CHANNEL_COLLABORATION

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

Update my user avatar

POST
https://peertube2.cpy.re/api/v1/users/me/avatar/pick

Body

multipart/form-data
multipart/form-dataobject
Encoding
avatarfileimage/png, image/jpeg
avatarfilestring<binary>

The file to upload

Response

200OKobject

successful operation

Response fields application/json
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>
413Payload Too Large

image file too large

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

Maximum file size for the avatar

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

DELETE
https://peertube2.cpy.re/api/v1/users/me/avatar

Response

204No Content

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

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

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

List my abuses

GET
https://peertube2.cpy.re/api/v1/users/me/abuses

Parameters

idintegerquery

only list the report with this id

stateAbuseStateSet123query
sortstring-id-createdAt-statequery

Sort abuses by criteria

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

Response

200OKobject

successful operation

Response fields application/json
totalinteger
Example
1
dataArray<Abuse>
Show child attributes
idid>= 1
Example
42
reasonstring
Example
The video is a spam
predefinedReasonsArray<string>violentOrAbusivehatefulOrAbusivespamOrMisleadingprivacyrightsserverRulesthumbnailscaptions
Example
[
  "spamOrMisleading"
]
reporterAccountActor & any
Show child attributes
idid>= 1
Example
42
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
42
displayNamestring

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

stateAbuseStateConstant
Show child attributes
idAbuseStateSet123

The abuse state (Pending = 1, Rejected = 2, Accepted = 3)

labelstring
moderationCommentstring
Example
Decided to ban the server since it spams us regularly
videoobject
Show child attributes
idinteger
uuidUUIDv4<uuid>
Example
9c9de5e8-0a1e-484a-b099-e80766180a6d
shortUUIDshortUUID

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

Example
2y84q2MQUMWPbiEcxNXMgC
namestring
nsfwboolean
startAtstring<date-time>
endAtstring<date-time>
deletedboolean
blacklistedboolean
thumbnailPathstring | nulldeprecated

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

thumbnailsArray<Thumbnail>

PeerTube >= 8.1 Array of thumbnails for the video

Show child attributes
fileUrlstring
widthinteger
heightinteger
aspectRatiostring
Example
16:9
channelActor & object
Show child attributes
idid>= 1
Example
42

Same fields as data.reporterAccount.userId

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
42

Same fields as data.reporterAccount.userId

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

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.

Docs by Sourcey
↑↓ navigate↵ selectesc close