Sign in

v1

latestOpenAPI 3.0.0AGPLv3.02026-07-14186117194.3 KB
Search

Search videos

get/api/v1/search/videos

Query parameters

searchstring required

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.

integer

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

OR
VideoCategorySet[]
Example:15

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

isLiveboolean

whether or not the video is a live

string
OR
string[]

tag(s) of the video

string
OR
string[]

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

integer

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

OR
VideoLicenceSet[]
Example:2

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

string

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

OR
VideoLanguageSet[]
Example:en

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

nsfw'true' | 'false'

whether to include nsfw videos, if any

isLocalboolean

PeerTube >= 4.0 Display only local or remote videos

include0 | 1 | 2 | 4 | 8

PeerTube >= 4.0 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
privacyOneOf1 | 2 | 3 | 4

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

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

uuidsstring[]

Find videos with specific UUIDs

hasHLSFilesboolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebtorrentFilesboolean

PeerTube >= 4.0 Display only videos that have WebTorrent files

skipCount'true' | 'false'

if you don't need the total in the response

startinteger

Offset used to paginate results

countinteger

Number of items to return

searchTarget'local' | 'search-index'

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
sort'name' | '-duration' | '-createdAt' | '-publishedAt' | '-views' | '-likes' | '-match'

Sort videos by criteria (prefixing with - means DESC order):

startDatestring date-time

Get videos that are published after this date

endDatestring date-time

Get videos that are published before this date

originallyPublishedStartDatestring date-time

Get videos that are originally published after this date

originallyPublishedEndDatestring date-time

Get videos that are originally published before this date

durationMininteger

Get videos that have this minimum duration

durationMaxinteger

Get videos that have this maximum duration

Response

successful operation

totalinteger

Example response

{
  "data": [
    {
      "category": {
        "id": 15,
        "label": "Science & Technology"
      },
      "channel": {
        "id": 42
      },
      "createdAt": "2017-10-01T10:52:46.396Z",
      "description": "**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\\r\\n\\r\\n\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\\r\\n*A decentralized video hosting network, based on fr...\n",
      "dislikes": 7,
      "duration": 1419,
      "embedPath": "/videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee",
      "id": 42,
      "language": {
        "id": "en",
        "label": "English"
      },
      "licence": {
        "id": 2,
        "label": "Attribution - Share Alike"
      },
      "likes": 42,
      "name": "What is PeerTube?",
      "originallyPublishedAt": "2010-10-01T10:52:46.396Z",
      "previewPath": "/lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg",
      "publishedAt": "2018-10-01T10:52:46.396Z",
      "shortUUID": "2y84q2MQUMWPbiEcxNXMgC",
      "thumbnailPath": "/static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg",
      "updatedAt": "2021-05-04T08:01:01.502Z",
      "uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
      "views": 1337
    }
  ],
  "total": 1
}