Search

Search videos

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

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

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

500Internal Server Error

search index unavailable

Docs by Sourcey
↑↓ navigate↵ selectesc close