Videos

Video Comments

Operations dealing with comments to a video. Comments are organized in threads: adding a comment in response to the video starts a thread, adding a reply to a comment adds it to its root comment thread.

List comments on user's videos

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

PeerTube >= 6.2

Parameters

searchstringquery

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

searchAccountstringquery

Filter comments by searching on the account

searchVideostringquery

Filter comments by searching on the video

videoIdintegerquery

Limit results on this specific video

videoChannelIdintegerquery

Limit results on this specific video channel

autoTagOneOfstring | Array<string>query

PeerTube >= 6.2 filter on comments that contain one of these automatic tags

isHeldForReviewbooleanquery

only display comments that are held for review

includeCollaborationsbooleanquery

PeerTube >= 8.0 Include objects from collaborated channels

Response

200OKobject

successful operation

Response fields application/json
totalinteger
Example
1
dataArray<VideoCommentForOwnerOrAdmin>
Show child attributes
idid>= 1
Example
42
urlurl<url>
texttext<html>

Text of the comment

Example
This video is wonderful!
heldForReviewheldForReview
threadIdid>= 1
Example
42
inReplyToCommentIdid | null
Show child attributes
id>= 1
Example
42
createdAtcreatedAt<date-time>
updatedAtupdatedAt<date-time>
accountActor & any
Show child attributes
idid>= 1
Example
42

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

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

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

title of the video

Example
What is PeerTube?
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
automaticTagsArray<string>

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

GET
https://peertube2.cpy.re/api/v1/videos/{id}/comment-threads

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

sortstring-createdAt-totalRepliesquery

Sort comments by criteria

x-peertube-video-passwordstringheader

Required on password protected video

Response

200OKCommentThreadResponse

successful operation

Response fields application/json
totalinteger

Total threads (included deleted ones) on this video

totalNotDeletedCommentsinteger

Total not-deleted threads (included deleted ones) on this video

dataArray<VideoComment>
Show child attributes
idid>= 1
Example
42
urlurl<url>
texttext<html>

Text of the comment

Example
This video is wonderful!
threadIdid>= 1
Example
42
inReplyToCommentIdid | null
Show child attributes
id>= 1
Example
42
videoIdid

object id for the video

Show child attributes
id>= 1
Example
42
createdAtcreatedAt<date-time>
updatedAtupdatedAt<date-time>
deletedAtstring<date-time> | nullnull
isDeletedbooleanfalse
heldForReviewheldForReview
totalRepliesFromVideoAuthorinteger>= 0
totalRepliesinteger>= 0
accountActor & any
Show child attributes
idid>= 1
Example
42

Same fields as data.videoId

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

Create a thread

POST
https://peertube2.cpy.re/api/v1/videos/{id}/comment-threads

Body

application/json
texttext<markdown>required
Show child attributes

Text of the comment

text<html>
Example
This video is wonderful!

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

Response

200OKCommentThreadPostResponse

successful operation

Response fields application/json
commentVideoComment
Show child attributes
idid>= 1
Example
42
urlurl<url>
texttext<html>

Text of the comment

Example
This video is wonderful!
threadIdid>= 1
Example
42
inReplyToCommentIdid | null
Show child attributes
id>= 1
Example
42
videoIdid

object id for the video

Show child attributes
id>= 1
Example
42
createdAtcreatedAt<date-time>
updatedAtupdatedAt<date-time>
deletedAtstring<date-time> | nullnull
isDeletedbooleanfalse
heldForReviewheldForReview
totalRepliesFromVideoAuthorinteger>= 0
totalRepliesinteger>= 0
accountActor & any
Show child attributes
idid>= 1
Example
42

Same fields as comment.videoId

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

404Not Found

video does not exist

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

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

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

Get a thread

GET
https://peertube2.cpy.re/api/v1/videos/{id}/comment-threads/{threadId}

Since PeerTube 8.3 the returned tree is truncated: only the first replies of each comment are included, and only down to maxDepth nesting levels. Use GET /api/v1/videos/{id}/comments/{commentId}/replies to fetch the replies that are missing, comparing children and totalChildren of each node of the tree.

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

threadIdintegerrequiredpath

The thread id (root comment id)

maxDepthinteger[1, 10]5query

Number of nesting levels to include below the requested comment. Bounded by repliesPerLevel and count, see the note on repliesPerLevel

repliesPerLevelinteger[1, 30]10query

Number of direct replies to include for each comment of the tree. Does not apply to the first level of GET /api/v1/videos/{id}/comments/{commentId}/replies, which is paginated using start and count. A tree can make the server walk through count * (repliesPerLevel ^ maxDepth - 1) / (repliesPerLevel - 1) comments, which grows exponentially. Combinations above 2000000 are rejected A deep tree has to be narrow and a wide tree has to be shallow.

x-peertube-video-passwordstringheader

Required on password protected video

Response

200OKVideoCommentThreadTree

successful operation

Response fields application/json
commentVideoComment
Show child attributes
idid>= 1
Example
42
urlurl<url>
texttext<html>

Text of the comment

Example
This video is wonderful!
threadIdid>= 1
Example
42
inReplyToCommentIdid | null
Show child attributes
id>= 1
Example
42
videoIdid

object id for the video

Show child attributes
id>= 1
Example
42
createdAtcreatedAt<date-time>
updatedAtupdatedAt<date-time>
deletedAtstring<date-time> | nullnull
isDeletedbooleanfalse
heldForReviewheldForReview
totalRepliesFromVideoAuthorinteger>= 0
totalRepliesinteger>= 0
accountActor & any
Show child attributes
idid>= 1
Example
42

Same fields as comment.videoId

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

childrenArray<VideoCommentThreadTree>

Direct replies of comment. The server truncates the tree in depth (see the maxDepth parameter) and in width, so this array may contain less elements than totalChildren. Missing replies can be fetched using GET /api/v1/videos/{id}/comments/{commentId}/replies

Same fields as VideoCommentThreadTree

totalChildreninteger>= 0

Total number of direct replies of comment the current user can see

List replies of a comment

GET
https://peertube2.cpy.re/api/v1/videos/{id}/comments/{commentId}/replies

PeerTube >= 8.3 List the direct replies of a comment, each of them nested up to maxDepth levels. Used to unfold the parts of a thread that GET /api/v1/videos/{id}/comment-threads/{threadId} truncated.

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

commentIdid>= 1requiredpath

The comment id

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

sortstringcreatedAt-createdAtcreatedAtquery

Sort the direct replies of the comment. Deeper levels of the tree are always sorted the same way. Defaults to createdAt so the replies are appended to the thread tree in the order it was built

maxDepthinteger[1, 10]5query

Number of nesting levels to include below the requested comment. Bounded by repliesPerLevel and count, see the note on repliesPerLevel

repliesPerLevelinteger[1, 30]10query

Number of direct replies to include for each comment of the tree. Does not apply to the first level of GET /api/v1/videos/{id}/comments/{commentId}/replies, which is paginated using start and count. A tree can make the server walk through count * (repliesPerLevel ^ maxDepth - 1) / (repliesPerLevel - 1) comments, which grows exponentially. Combinations above 2000000 are rejected A deep tree has to be narrow and a wide tree has to be shallow.

x-peertube-video-passwordstringheader

Required on password protected video

Response

200OKobject

successful operation

Response fields application/json
totalinteger

Total number of direct replies of the comment

Example
13
dataArray<VideoCommentThreadTree>
Show child attributes
commentVideoComment
Show child attributes
idid>= 1
Example
42
urlurl<url>
texttext<html>

Text of the comment

Example
This video is wonderful!
threadIdid>= 1
Example
42
inReplyToCommentIdid | null
Show child attributes
id>= 1
Example
42
videoIdid

object id for the video

Show child attributes
id>= 1
Example
42
createdAtcreatedAt<date-time>
updatedAtupdatedAt<date-time>
deletedAtstring<date-time> | nullnull
isDeletedbooleanfalse
heldForReviewheldForReview
totalRepliesFromVideoAuthorinteger>= 0
totalRepliesinteger>= 0
accountActor & any
Show child attributes
idid>= 1
Example
42

Same fields as data.comment.videoId

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

childrenArray<VideoCommentThreadTree>

Direct replies of comment. The server truncates the tree in depth (see the maxDepth parameter) and in width, so this array may contain less elements than totalChildren. Missing replies can be fetched using GET /api/v1/videos/{id}/comments/{commentId}/replies

Same fields as data

totalChildreninteger>= 0

Total number of direct replies of comment the current user can see

List instance comments

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

Parameters

searchstringquery

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

searchAccountstringquery

Filter comments by searching on the account

searchVideostringquery

Filter comments by searching on the video

videoIdintegerquery

Limit results on this specific video

videoChannelIdintegerquery

Limit results on this specific video channel

autoTagOneOfstring | Array<string>query

PeerTube >= 6.2 filter on comments that contain one of these automatic tags

isLocalbooleanquery

PeerTube >= 4.0 Display only local or remote objects

onLocalVideobooleanquery

Display only objects of local or remote videos

includeMutedbooleanquery

PeerTube >= 8.2 Include comments from muted accounts

Response

200OKobject

successful operation

Response fields application/json
totalinteger
Example
1
dataArray<VideoCommentForOwnerOrAdmin>
Show child attributes
idid>= 1
Example
42
urlurl<url>
texttext<html>

Text of the comment

Example
This video is wonderful!
heldForReviewheldForReview
threadIdid>= 1
Example
42
inReplyToCommentIdid | null
Show child attributes
id>= 1
Example
42
createdAtcreatedAt<date-time>
updatedAtupdatedAt<date-time>
accountActor & any
Show child attributes
idid>= 1
Example
42

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

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

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

title of the video

Example
What is PeerTube?
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
automaticTagsArray<string>

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

Reply to a thread of a video

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

Body

application/json
texttext<markdown>required
Show child attributes

Text of the comment

text<html>
Example
This video is wonderful!

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

commentIdid>= 1requiredpath

The comment id

x-peertube-video-passwordstringheader

Required on password protected video

Response

200OKCommentThreadPostResponse

successful operation

Response fields application/json
commentVideoComment
Show child attributes
idid>= 1
Example
42
urlurl<url>
texttext<html>

Text of the comment

Example
This video is wonderful!
threadIdid>= 1
Example
42
inReplyToCommentIdid | null
Show child attributes
id>= 1
Example
42
videoIdid

object id for the video

Show child attributes
id>= 1
Example
42
createdAtcreatedAt<date-time>
updatedAtupdatedAt<date-time>
deletedAtstring<date-time> | nullnull
isDeletedbooleanfalse
heldForReviewheldForReview
totalRepliesFromVideoAuthorinteger>= 0
totalRepliesinteger>= 0
accountActor & any
Show child attributes
idid>= 1
Example
42

Same fields as comment.videoId

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

404Not Found

thread or video does not exist

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 comment or a reply

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

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

commentIdid>= 1requiredpath

The comment id

Response

204No Content

successful operation

403Forbidden

cannot remove comment of another user

404Not Found

comment or video does not exist

409Conflict

comment is already deleted

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.

Approve a comment

POST
https://peertube2.cpy.re/api/v1/videos/{id}/comments/{commentId}/approve

PeerTube >= 6.2 Approve a comment that requires a review

Parameters

idid | UUIDv4 | shortUUIDrequiredpath

The object id, uuid or short uuid

commentIdid>= 1requiredpath

The comment id

Response

204No Content

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

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

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

Docs by Sourcey
↑↓ navigate↵ selectesc close