6 name: PeerTube Community
7 url: https://joinpeertube.org
10 url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
12 url: https://joinpeertube.org/img/brand.png
13 altText: PeerTube Project Homepage
15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
16 HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
17 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
18 which generates a client SDK in the language of your choice - we generate some client SDKs automatically:
20 - [Python](https://framagit.org/framasoft/peertube/clients/python)
21 - [Go](https://framagit.org/framasoft/peertube/clients/go)
22 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
24 See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
25 examples of using the PeerTube API.
29 When you sign up for an account on a PeerTube instance, you are given the possibility
30 to generate sessions on it, and authenticate there using an access token. Only __one
31 access token can currently be used at a time__.
35 Accounts are given permissions based on their role. There are three roles on
36 PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions.
40 The API uses standard HTTP status codes to indicate the success or failure
41 of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
44 HTTP 1.1 404 Not Found
45 Content-Type: application/problem+json; charset=utf-8
48 "detail": "Video not found",
49 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
56 We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
57 but it is still optional. Types are used to disambiguate errors that bear the same status code
61 HTTP 1.1 403 Forbidden
62 Content-Type: application/problem+json; charset=utf-8
65 "detail": "Cannot get this video regarding follow constraints",
66 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
69 "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
73 Here a 403 error could otherwise mean that the video is private or blocklisted.
77 Each parameter is evaluated on its own against a set of rules before the route validator
78 proceeds with potential testing involving parameter combinations. Errors coming from validation
79 errors appear earlier and benefit from a more detailed error description:
82 HTTP 1.1 400 Bad Request
83 Content-Type: application/problem+json; charset=utf-8
86 "detail": "Incorrect request parameters: id",
87 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
88 "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
92 "msg": "Invalid value",
94 "value": "9c9de5e8-0a1e-484a-b099-e80766180"
98 "title": "Bad Request",
103 Where `id` is the name of the field concerned by the error, within the route definition.
104 `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
105 `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
108 ### Deprecated error fields
110 Some fields could be included with previous versions. They are still included but their use is deprecated:
111 - `error`: superseded by `detail`
112 - `code`: superseded by `type` (which is now an URI)
116 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
118 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
119 |------------------------------|---------------|--------------|
120 | `/*` | 50 | 10 seconds |
121 | `POST /users/token` | 15 | 5 minutes |
122 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
123 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
125 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
126 limit is announced by a `429 Too Many Requests` status code.
128 You can get details about the current state of your rate limit by reading the
131 | Header | Description |
132 |-------------------------|------------------------------------------------------------|
133 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
134 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
135 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
136 | `Retry-After` | Seconds to delay after the first `429` is received |
140 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
141 allowing cross-domain communication from the browser for some routes:
144 |------------------------- ---|
148 | `/.well-known/webfinger` |
150 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
152 url: https://docs.joinpeertube.org/api-rest-reference.html
156 As a visitor, you can use this API to open an account (if registrations are open on
157 that PeerTube instance). As an admin, you should use the dedicated [User creation
158 API](#operation/addUser) instead.
160 x-displayName: Login/Logout
162 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
165 Accounts encompass remote accounts discovered across the federation,
166 and correspond to the main Actor, along with video channels a user can create, which
169 When a comment is posted, it is done with your Account's Actor.
172 Using some features of PeerTube require authentication, for which User
173 provide different levels of permission as well as associated user
174 information. Each user has a corresponding local Account for federation.
177 Operations related to your own User, when logged-in.
178 - name: My Subscriptions
180 Operations related to your subscriptions to video channels, their
181 new videos, and how to keep up to date with their latest publications!
184 Operations related to your watch history.
185 - name: My Notifications
187 Notifications following new videos, follows or reports. They allow you
188 to keep track of the interactions and overall important information that
189 concerns you. You MAY set per-notification type delivery preference, to
190 receive the info either by mail, by in-browser notification or both.
193 Each server exposes public information regarding supported videos and
197 Jobs are long-running tasks enqueued and processed by the instance
198 itself. No additional worker registration is currently available.
199 - name: Instance Follows
201 Managing servers which the instance interacts with is crucial to the
202 concept of federation in PeerTube and external video indexation. The PeerTube
203 server then deals with inter-server ActivityPub operations and propagates
204 information across its social graph by posting activities to actors' inbox
207 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
208 - name: Instance Redundancy
210 Redundancy is part of the inter-server solidarity that PeerTube fosters.
211 Manage the list of instances you wish to help by seeding their videos according
212 to the policy of video selection of your choice. Note that you have a similar functionality
213 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
215 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
218 Managing plugins installed from a local path or from NPM, or search for new ones.
220 url: https://docs.joinpeertube.org/api-plugins
223 Abuses deal with reports of local or remote videos/comments/accounts alike.
226 Operations dealing with listing, uploading, fetching or modifying videos.
229 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
233 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
234 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
236 You can upload videos more reliably by using the resumable variant. Its protocol lets
237 you resume an upload operation after a network interruption or other transmission failure,
238 saving time and bandwidth in the event of network failures.
240 Favor using resumable uploads in any of the following cases:
241 - You are transferring large files
242 - The likelihood of a network interruption is high
243 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
244 such as a mobile device
248 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
249 - _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file
250 - _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file
252 The import function is practical when the desired video/audio is available online. It makes PeerTube
253 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
254 - name: Video Imports
255 description: Operations dealing with listing, adding and removing video imports.
256 - name: Channels Sync
257 description: Operations dealing with synchronizing PeerTube user's channel with channels of other platforms
258 - name: Video Captions
259 description: Operations dealing with listing, adding and removing closed captions of a video.
260 - name: Video Channels
261 description: Operations dealing with the creation, modification and listing of videos within a channel.
262 - name: Video Comments
264 Operations dealing with comments to a video. Comments are organized in threads: adding a
265 comment in response to the video starts a thread, adding a reply to a comment adds it to
266 its root comment thread.
268 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
270 description: Like/dislike a video.
271 - name: Video Playlists
272 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
274 description: Operations on video files
275 - name: Video Transcoding
276 description: Video transcoding related operations
278 description: Video statistics
280 description: Server syndication feeds of videos
283 The search helps to find _videos_ or _channels_ from within the instance and beyond.
284 Videos from other instances federated by the instance (that is, instances
285 followed by the instance) can be found via keywords and other criteria of
288 Administrators can also enable the use of a remote search system, indexing
289 videos and channels not could be not federated by the instance.
291 description: Get and update the custom homepage
292 - name: Video Mirroring
294 PeerTube instances can mirror videos from one another, and help distribute some videos.
296 For importing videos as your own, refer to [video imports](#operation/importVideo).
302 - name: Static endpoints
331 - Video Ownership Change
351 - Instance Redundancy
357 '/static/webseed/{filename}':
361 summary: Get public WebTorrent video file
363 - $ref: '#/components/parameters/staticFilename'
366 description: successful operation
368 description: not found
369 '/static/webseed/private/{filename}':
373 summary: Get private WebTorrent video file
375 - $ref: '#/components/parameters/staticFilename'
376 - $ref: '#/components/parameters/videoFileToken'
381 description: successful operation
383 description: invalid auth
385 description: not found
387 '/static/streaming-playlists/hls/{filename}':
391 summary: Get public HLS video file
393 - $ref: '#/components/parameters/staticFilename'
398 description: successful operation
400 description: invalid auth
402 description: not found
403 '/static/streaming-playlists/hls/private/{filename}':
407 summary: Get private HLS video file
409 - $ref: '#/components/parameters/staticFilename'
410 - $ref: '#/components/parameters/videoFileToken'
411 - $ref: '#/components/parameters/reinjectVideoFileToken'
416 description: successful operation
418 description: invalid auth
420 description: not found
423 '/feeds/video-comments.{format}':
427 summary: List comments on videos
428 operationId: getSyndicatedComments
433 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
446 description: 'limit listing to a specific video'
451 description: 'limit listing to a specific account'
456 description: 'limit listing to a specific account'
459 - name: videoChannelId
461 description: 'limit listing to a specific video channel'
464 - name: videoChannelName
466 description: 'limit listing to a specific video channel'
471 description: successful operation
476 default: 'max-age=900' # 15 min cache
480 $ref: '#/components/schemas/VideoCommentsForXML'
483 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
486 $ref: '#/components/schemas/VideoCommentsForXML'
489 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
492 $ref: '#/components/schemas/VideoCommentsForXML'
495 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
496 application/atom+xml:
498 $ref: '#/components/schemas/VideoCommentsForXML'
501 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
507 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
509 x-summary: field inconsistencies
512 - videoId filter is mixed with a channel filter
514 description: video, video channel or account not found
516 description: accept header unsupported
518 '/feeds/videos.{format}':
523 operationId: getSyndicatedVideos
528 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
541 description: 'limit listing to a specific account'
546 description: 'limit listing to a specific account'
549 - name: videoChannelId
551 description: 'limit listing to a specific video channel'
554 - name: videoChannelName
556 description: 'limit listing to a specific video channel'
559 - $ref: '#/components/parameters/sort'
560 - $ref: '#/components/parameters/nsfw'
561 - $ref: '#/components/parameters/isLocal'
562 - $ref: '#/components/parameters/include'
563 - $ref: '#/components/parameters/privacyOneOf'
564 - $ref: '#/components/parameters/hasHLSFiles'
565 - $ref: '#/components/parameters/hasWebtorrentFiles'
568 description: successful operation
573 default: 'max-age=900' # 15 min cache
577 $ref: '#/components/schemas/VideosForXML'
580 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
583 $ref: '#/components/schemas/VideosForXML'
586 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
589 $ref: '#/components/schemas/VideosForXML'
592 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
593 application/atom+xml:
595 $ref: '#/components/schemas/VideosForXML'
598 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
604 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
606 description: video channel or account not found
608 description: accept header unsupported
610 '/feeds/subscriptions.{format}':
614 summary: List videos of subscriptions tied to a token
615 operationId: getSyndicatedSubscriptionVideos
620 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
633 description: limit listing to a specific account
639 description: private token allowing access
643 - $ref: '#/components/parameters/sort'
644 - $ref: '#/components/parameters/nsfw'
645 - $ref: '#/components/parameters/isLocal'
646 - $ref: '#/components/parameters/include'
647 - $ref: '#/components/parameters/privacyOneOf'
648 - $ref: '#/components/parameters/hasHLSFiles'
649 - $ref: '#/components/parameters/hasWebtorrentFiles'
652 description: successful operation
657 default: 'max-age=900' # 15 min cache
661 $ref: '#/components/schemas/VideosForXML'
664 $ref: '#/components/schemas/VideosForXML'
667 $ref: '#/components/schemas/VideosForXML'
668 application/atom+xml:
670 $ref: '#/components/schemas/VideosForXML'
675 description: accept header unsupported
677 '/api/v1/accounts/{name}':
681 summary: Get an account
682 operationId: getAccount
684 - $ref: '#/components/parameters/name'
687 description: successful operation
691 $ref: '#/components/schemas/Account'
693 description: account not found
695 '/api/v1/accounts/{name}/videos':
700 summary: 'List videos of an account'
701 operationId: getAccountVideos
703 - $ref: '#/components/parameters/name'
704 - $ref: '#/components/parameters/categoryOneOf'
705 - $ref: '#/components/parameters/isLive'
706 - $ref: '#/components/parameters/tagsOneOf'
707 - $ref: '#/components/parameters/tagsAllOf'
708 - $ref: '#/components/parameters/licenceOneOf'
709 - $ref: '#/components/parameters/languageOneOf'
710 - $ref: '#/components/parameters/nsfw'
711 - $ref: '#/components/parameters/isLocal'
712 - $ref: '#/components/parameters/include'
713 - $ref: '#/components/parameters/privacyOneOf'
714 - $ref: '#/components/parameters/hasHLSFiles'
715 - $ref: '#/components/parameters/hasWebtorrentFiles'
716 - $ref: '#/components/parameters/skipCount'
717 - $ref: '#/components/parameters/start'
718 - $ref: '#/components/parameters/count'
719 - $ref: '#/components/parameters/videosSort'
722 description: successful operation
726 $ref: '#/components/schemas/VideoListResponse'
730 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
731 .then(function(response) {
732 return response.json()
733 }).then(function(data) {
739 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
745 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
747 http = Net::HTTP.new(uri.host, uri.port)
750 response = http.get(uri.request_uri)
752 puts JSON.parse(response.read_body)
757 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
762 '/api/v1/accounts/{name}/followers':
766 summary: 'List followers of an account'
769 operationId: getAccountFollowers
771 - $ref: '#/components/parameters/name'
772 - $ref: '#/components/parameters/start'
773 - $ref: '#/components/parameters/count'
774 - $ref: '#/components/parameters/followersSort'
775 - $ref: '#/components/parameters/search'
778 description: successful operation
790 $ref: '#/components/schemas/Follow'
796 summary: List accounts
797 operationId: getAccounts
799 - $ref: '#/components/parameters/start'
800 - $ref: '#/components/parameters/count'
801 - $ref: '#/components/parameters/sort'
804 description: successful operation
810 $ref: '#/components/schemas/Account'
816 summary: Get instance public configuration
817 operationId: getConfig
820 description: successful operation
824 $ref: '#/components/schemas/ServerConfig'
827 externalValue: https://peertube2.cpy.re/api/v1/config
829 /api/v1/config/about:
831 summary: Get instance "About" information
832 operationId: getAbout
837 description: successful operation
841 $ref: '#/components/schemas/ServerConfigAbout'
844 externalValue: https://peertube2.cpy.re/api/v1/config/about
846 /api/v1/config/custom:
848 summary: Get instance runtime configuration
849 operationId: getCustomConfig
857 description: successful operation
861 $ref: '#/components/schemas/ServerConfigCustom'
863 summary: Set instance runtime configuration
864 operationId: putCustomConfig
872 description: successful operation
874 x-summary: field inconsistencies
877 - the emailer is disabled and the instance is open to registrations
878 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
880 summary: Delete instance runtime configuration
881 operationId: delCustomConfig
889 description: successful operation
891 /api/v1/custom-pages/homepage/instance:
893 summary: Get instance custom homepage
898 description: No homepage set
900 description: successful operation
904 $ref: '#/components/schemas/CustomHomepage'
906 summary: Set instance custom homepage
920 description: content of the homepage, that will be injected in the client
923 description: successful operation
927 summary: Pause job queue
935 description: successful operation
939 summary: Resume job queue
947 description: successful operation
949 /api/v1/jobs/{state}:
951 summary: List instance jobs
962 description: The state of the job ('' for for no filter)
972 - $ref: '#/components/parameters/jobType'
973 - $ref: '#/components/parameters/start'
974 - $ref: '#/components/parameters/count'
975 - $ref: '#/components/parameters/sort'
978 description: successful operation
991 $ref: '#/components/schemas/Job'
993 /api/v1/server/followers:
997 summary: List instances following the server
999 - $ref: '#/components/parameters/followState'
1000 - $ref: '#/components/parameters/actorType'
1001 - $ref: '#/components/parameters/start'
1002 - $ref: '#/components/parameters/count'
1003 - $ref: '#/components/parameters/sort'
1006 description: successful operation
1018 $ref: '#/components/schemas/Follow'
1020 '/api/v1/server/followers/{nameWithHost}':
1022 summary: Remove or reject a follower to your server
1029 - name: nameWithHost
1032 description: The remote actor handle to remove from your followers
1038 description: successful operation
1040 description: follower not found
1042 '/api/v1/server/followers/{nameWithHost}/reject':
1044 summary: Reject a pending follower to your server
1051 - name: nameWithHost
1054 description: The remote actor handle to remove from your followers
1060 description: successful operation
1062 description: follower not found
1064 '/api/v1/server/followers/{nameWithHost}/accept':
1066 summary: Accept a pending follower to your server
1073 - name: nameWithHost
1076 description: The remote actor handle to remove from your followers
1082 description: successful operation
1084 description: follower not found
1086 /api/v1/server/following:
1090 summary: List instances followed by the server
1092 - $ref: '#/components/parameters/followState'
1093 - $ref: '#/components/parameters/actorType'
1094 - $ref: '#/components/parameters/start'
1095 - $ref: '#/components/parameters/count'
1096 - $ref: '#/components/parameters/sort'
1099 description: successful operation
1111 $ref: '#/components/schemas/Follow'
1118 summary: Follow a list of actors (PeerTube instance, channel or account)
1121 description: successful operation
1123 description: cannot follow a non-HTTPS server
1142 '/api/v1/server/following/{hostOrHandle}':
1144 summary: Unfollow an actor (PeerTube instance, channel or account)
1151 - name: hostOrHandle
1154 description: The hostOrHandle to unfollow
1159 description: successful operation
1161 description: host or handle not found
1165 summary: Create a user
1166 operationId: addUser
1174 description: user created
1178 $ref: '#/components/schemas/AddUserResponse'
1182 operationId: getUser
1184 id: '$response.body#/user/id'
1187 operationId: putUser
1189 id: '$response.body#/user/id'
1190 # DELETE /users/{id}
1192 operationId: delUser
1194 id: '$response.body#/user/id'
1196 description: insufficient authority to create an admin or moderator
1201 $ref: '#/components/schemas/AddUser'
1203 If the smtp server is configured, you can leave the password empty and an email will be sent
1204 asking the user to set it first.
1208 operationId: getUsers
1215 - $ref: '#/components/parameters/usersSearch'
1216 - $ref: '#/components/parameters/usersBlocked'
1217 - $ref: '#/components/parameters/start'
1218 - $ref: '#/components/parameters/count'
1219 - $ref: '#/components/parameters/usersSort'
1222 description: successful operation
1228 $ref: '#/components/schemas/User'
1230 '/api/v1/users/{id}':
1232 - $ref: '#/components/parameters/id'
1234 summary: Delete a user
1240 operationId: delUser
1243 description: successful operation
1250 operationId: getUser
1254 description: include statistics about the user (only available as a moderator/admin)
1259 x-summary: successful operation
1261 As an admin/moderator, you can request a response augmented with statistics about the user's
1262 moderation relations and videos usage, by using the `withStats` parameter.
1267 - $ref: '#/components/schemas/User'
1268 - $ref: '#/components/schemas/UserWithStats'
1270 summary: Update a user
1275 operationId: putUser
1278 description: successful operation
1283 $ref: '#/components/schemas/UpdateUser'
1286 /api/v1/oauth-clients/local:
1288 summary: Login prerequisite
1289 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
1290 operationId: getOAuthClient
1295 description: successful operation
1299 $ref: '#/components/schemas/OAuthClient'
1301 UseOAuthClientToLogin:
1302 operationId: getOAuthToken
1304 client_id: '$response.body#/client_id'
1305 client_secret: '$response.body#/client_secret'
1309 API="https://peertube2.cpy.re/api/v1"
1312 curl -s "$API/oauth-clients/local"
1314 /api/v1/users/token:
1317 operationId: getOAuthToken
1318 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
1323 application/x-www-form-urlencoded:
1326 - $ref: '#/components/schemas/OAuthToken-password'
1327 - $ref: '#/components/schemas/OAuthToken-refresh_token'
1329 propertyName: grant_type
1331 password: '#/components/schemas/OAuthToken-password'
1332 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
1335 description: successful operation
1346 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
1347 description: valid for 1 day
1350 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
1351 description: valid for 2 weeks
1356 refresh_token_expires_in:
1361 x-summary: client or credentials are invalid
1363 Disambiguate via `type`:
1364 - `invalid_client` for an unmatched `client_id`
1365 - `invalid_grant` for unmatched credentials
1367 x-summary: token expired
1369 Disambiguate via `type`:
1370 - default value for a regular authentication failure
1371 - `invalid_token` for an expired token
1376 API="https://peertube2.cpy.re/api/v1"
1377 USERNAME="<your_username>"
1378 PASSWORD="<your_password>"
1381 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1382 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1383 curl -s "$API/users/token" \
1384 --data client_id="$client_id" \
1385 --data client_secret="$client_secret" \
1386 --data grant_type=password \
1387 --data username="$USERNAME" \
1388 --data password="$PASSWORD" \
1389 | jq -r ".access_token"
1391 /api/v1/users/revoke-token:
1394 description: Revokes your access token and its associated refresh token, destroying your current session.
1395 operationId: revokeOAuthToken
1402 description: successful operation
1404 /api/v1/users/ask-send-verify-email:
1406 summary: Resend user verification link
1407 operationId: resendEmailToVerifyUser
1419 description: User email
1422 description: successful operation
1424 /api/v1/users/registrations/ask-send-verify-email:
1426 summary: Resend verification link to registration email
1427 operationId: resendEmailToVerifyRegistration
1438 description: Registration email
1441 description: successful operation
1443 /api/v1/users/{id}/verify-email:
1445 summary: Verify a user
1446 operationId: verifyUser
1448 Following a user registration, the new user will receive an email asking to click a link
1449 containing a secret.
1450 This endpoint can also be used to verify a new email set in the user account.
1455 - $ref: '#/components/parameters/id'
1468 - verificationString
1471 description: successful operation
1473 description: invalid verification string
1475 description: user not found
1477 /api/v1/users/registrations/{registrationId}/verify-email:
1479 summary: Verify a registration email
1480 operationId: verifyRegistrationEmail
1482 Following a user registration request, the user will receive an email asking to click a link
1483 containing a secret.
1487 - $ref: '#/components/parameters/registrationId'
1498 - verificationString
1501 description: successful operation
1503 description: invalid verification string
1505 description: registration not found
1507 /api/v1/users/{id}/two-factor/request:
1509 summary: Request two factor auth
1510 operationId: requestTwoFactor
1511 description: Request two factor authentication for a user
1515 - $ref: '#/components/parameters/id'
1524 description: Password of the currently authenticated user
1527 description: successful operation
1533 $ref: '#/components/schemas/RequestTwoFactorResponse'
1535 description: invalid password
1537 description: user not found
1539 /api/v1/users/{id}/two-factor/confirm-request:
1541 summary: Confirm two factor auth
1542 operationId: confirmTwoFactorRequest
1543 description: Confirm a two factor authentication request
1547 - $ref: '#/components/parameters/id'
1556 description: Token to identify the two factor request
1559 description: OTP token generated by the app
1565 description: successful operation
1567 description: invalid request token or OTP token
1569 description: user not found
1571 /api/v1/users/{id}/two-factor/disable:
1573 summary: Disable two factor auth
1574 operationId: disableTwoFactor
1575 description: Disable two factor authentication of a user
1579 - $ref: '#/components/parameters/id'
1588 description: Password of the currently authenticated user
1591 description: successful operation
1593 description: invalid password
1595 description: user not found
1599 summary: Get my user information
1600 operationId: getUserInfo
1608 description: successful operation
1614 $ref: '#/components/schemas/User'
1616 summary: Update my user information
1617 operationId: putUserInfo
1625 description: successful operation
1630 $ref: '#/components/schemas/UpdateMe'
1633 /api/v1/users/me/videos/imports:
1635 summary: Get video imports of my user
1643 - $ref: '#/components/parameters/start'
1644 - $ref: '#/components/parameters/count'
1645 - $ref: '#/components/parameters/sort'
1650 description: Filter on import target URL
1654 name: videoChannelSyncId
1657 description: Filter on imports created by a specific channel synchronization
1664 description: Search in video names
1669 description: successful operation
1673 $ref: '#/components/schemas/VideoImportsList'
1675 /api/v1/users/me/video-quota-used:
1677 summary: Get my user used quota
1685 description: successful operation
1693 description: The user video quota used so far in bytes
1694 example: 16810141515
1695 videoQuotaUsedDaily:
1697 description: The user video quota used today in bytes
1700 '/api/v1/users/me/videos/{videoId}/rating':
1702 summary: Get rate of my user for a video
1712 description: The video id
1714 $ref: '#/components/schemas/Video/properties/id'
1717 description: successful operation
1721 $ref: '#/components/schemas/GetMeVideoRating'
1723 /api/v1/users/me/videos:
1725 summary: Get videos of my user
1733 - $ref: '#/components/parameters/start'
1734 - $ref: '#/components/parameters/count'
1735 - $ref: '#/components/parameters/sort'
1738 description: successful operation
1742 $ref: '#/components/schemas/VideoListResponse'
1744 /api/v1/users/me/subscriptions:
1746 summary: Get my user subscriptions
1753 - $ref: '#/components/parameters/start'
1754 - $ref: '#/components/parameters/count'
1755 - $ref: '#/components/parameters/sort'
1758 description: successful operation
1762 $ref: '#/components/schemas/VideoChannelList'
1766 summary: Add subscription to my user
1779 description: uri of the video channels to subscribe to
1785 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1788 description: successful operation
1790 /api/v1/users/me/subscriptions/exist:
1792 summary: Get if subscriptions exist for my user
1799 - $ref: '#/components/parameters/subscriptionsUris'
1802 description: successful operation
1808 /api/v1/users/me/subscriptions/videos:
1810 summary: List videos of subscriptions of my user
1818 - $ref: '#/components/parameters/categoryOneOf'
1819 - $ref: '#/components/parameters/isLive'
1820 - $ref: '#/components/parameters/tagsOneOf'
1821 - $ref: '#/components/parameters/tagsAllOf'
1822 - $ref: '#/components/parameters/licenceOneOf'
1823 - $ref: '#/components/parameters/languageOneOf'
1824 - $ref: '#/components/parameters/nsfw'
1825 - $ref: '#/components/parameters/isLocal'
1826 - $ref: '#/components/parameters/include'
1827 - $ref: '#/components/parameters/privacyOneOf'
1828 - $ref: '#/components/parameters/hasHLSFiles'
1829 - $ref: '#/components/parameters/hasWebtorrentFiles'
1830 - $ref: '#/components/parameters/skipCount'
1831 - $ref: '#/components/parameters/start'
1832 - $ref: '#/components/parameters/count'
1833 - $ref: '#/components/parameters/videosSort'
1836 description: successful operation
1840 $ref: '#/components/schemas/VideoListResponse'
1842 '/api/v1/users/me/subscriptions/{subscriptionHandle}':
1844 summary: Get subscription of my user
1851 - $ref: '#/components/parameters/subscriptionHandle'
1854 description: successful operation
1858 $ref: '#/components/schemas/VideoChannel'
1860 summary: Delete subscription of my user
1867 - $ref: '#/components/parameters/subscriptionHandle'
1870 description: successful operation
1872 /api/v1/users/me/notifications:
1874 summary: List my notifications
1882 description: only list unread notifications
1885 - $ref: '#/components/parameters/start'
1886 - $ref: '#/components/parameters/count'
1887 - $ref: '#/components/parameters/sort'
1890 description: successful operation
1894 $ref: '#/components/schemas/NotificationListResponse'
1896 /api/v1/users/me/notifications/read:
1898 summary: Mark notifications as read by their id
1911 description: ids of the notifications to mark as read
1918 description: successful operation
1920 /api/v1/users/me/notifications/read-all:
1922 summary: Mark all my notification as read
1929 description: successful operation
1931 /api/v1/users/me/notification-settings:
1933 summary: Update my notification settings
1944 newVideoFromSubscription:
1945 $ref: '#/components/schemas/NotificationSettingValue'
1946 newCommentOnMyVideo:
1947 $ref: '#/components/schemas/NotificationSettingValue'
1949 $ref: '#/components/schemas/NotificationSettingValue'
1950 videoAutoBlacklistAsModerator:
1951 $ref: '#/components/schemas/NotificationSettingValue'
1953 $ref: '#/components/schemas/NotificationSettingValue'
1955 $ref: '#/components/schemas/NotificationSettingValue'
1956 myVideoImportFinished:
1957 $ref: '#/components/schemas/NotificationSettingValue'
1959 $ref: '#/components/schemas/NotificationSettingValue'
1960 newUserRegistration:
1961 $ref: '#/components/schemas/NotificationSettingValue'
1963 $ref: '#/components/schemas/NotificationSettingValue'
1964 newInstanceFollower:
1965 $ref: '#/components/schemas/NotificationSettingValue'
1966 autoInstanceFollowing:
1967 $ref: '#/components/schemas/NotificationSettingValue'
1970 description: successful operation
1972 /api/v1/users/me/history/videos:
1974 summary: List watched videos history
1980 - $ref: '#/components/parameters/start'
1981 - $ref: '#/components/parameters/count'
1982 - $ref: '#/components/parameters/search'
1985 description: successful operation
1989 $ref: '#/components/schemas/VideoListResponse'
1991 /api/v1/users/me/history/videos/{videoId}:
1993 summary: Delete history element
2003 $ref: '#/components/schemas/Video/properties/id'
2006 description: successful operation
2008 /api/v1/users/me/history/videos/remove:
2010 summary: Clear video history
2017 multipart/form-data:
2022 description: history before this date will be deleted
2027 description: successful operation
2029 /api/v1/users/me/avatar/pick:
2031 summary: Update my user avatar
2038 description: successful operation
2047 $ref: '#/components/schemas/ActorImage'
2049 description: image file too large
2051 X-File-Maximum-Size:
2055 description: Maximum file size for the avatar
2058 multipart/form-data:
2063 description: The file to upload
2068 contentType: image/png, image/jpeg
2070 /api/v1/users/me/avatar:
2072 summary: Delete my avatar
2079 description: successful operation
2081 /api/v1/users/register:
2083 summary: Register a user
2084 operationId: registerUser
2085 description: Signup has to be enabled and signup approval is not required
2090 description: successful operation
2092 description: request error
2094 description: user registration is not enabled, user limit is reached, registration is not allowed for the ip, requires approval or blocked by a plugin
2096 description: 'a user with this username, channel name or email already exists'
2101 $ref: '#/components/schemas/RegisterUser'
2104 /api/v1/users/registrations/request:
2106 summary: Request registration
2107 description: Signup has to be enabled and require approval on the instance
2108 operationId: requestRegistration
2113 description: successful operation
2117 $ref: '#/components/schemas/UserRegistration'
2119 description: request error or signup approval is not enabled on the instance
2121 description: user registration is not enabled, user limit is reached, registration is not allowed for the ip or blocked by a plugin
2123 description: 'a user or registration with this username, channel name or email already exists'
2128 $ref: '#/components/schemas/UserRegistrationRequest'
2130 /api/v1/users/registrations/{registrationId}/accept:
2136 summary: Accept registration
2137 operationId: acceptRegistration
2141 - $ref: '#/components/parameters/registrationId'
2146 $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
2149 description: successful operation
2151 /api/v1/users/registrations/{registrationId}/reject:
2157 summary: Reject registration
2158 operationId: rejectRegistration
2162 - $ref: '#/components/parameters/registrationId'
2167 $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
2170 description: successful operation
2172 /api/v1/users/registrations/{registrationId}:
2178 summary: Delete registration
2179 description: 'Delete the registration entry. It will not remove the user associated with this registration (if any)'
2180 operationId: deleteRegistration
2184 - $ref: '#/components/parameters/registrationId'
2187 description: successful operation
2189 /api/v1/users/registrations:
2195 summary: List registrations
2196 operationId: listRegistrations
2200 - $ref: '#/components/parameters/start'
2201 - $ref: '#/components/parameters/count'
2219 description: successful operation
2221 /api/v1/videos/ownership:
2223 summary: List video ownership changes
2225 - Video Ownership Change
2230 description: successful operation
2232 '/api/v1/videos/ownership/{id}/accept':
2234 summary: Accept ownership change request
2236 - Video Ownership Change
2240 - $ref: '#/components/parameters/idOrUUID'
2243 description: successful operation
2245 description: cannot terminate an ownership change of another user
2247 description: video ownership change not found
2249 '/api/v1/videos/ownership/{id}/refuse':
2251 summary: Refuse ownership change request
2253 - Video Ownership Change
2257 - $ref: '#/components/parameters/idOrUUID'
2260 description: successful operation
2262 description: cannot terminate an ownership change of another user
2264 description: video ownership change not found
2266 '/api/v1/videos/{id}/give-ownership':
2268 summary: Request ownership change
2270 - Video Ownership Change
2274 - $ref: '#/components/parameters/idOrUUID'
2278 application/x-www-form-urlencoded:
2288 description: successful operation
2290 description: changing video ownership to a remote account is not supported yet
2292 description: video not found
2294 '/api/v1/videos/{id}/token':
2296 summary: Request video token
2297 operationId: requestVideoToken
2298 description: Request special tokens that expire quickly to use them in some context (like accessing private static files)
2304 - $ref: '#/components/parameters/idOrUUID'
2307 description: successful operation
2311 $ref: '#/components/schemas/VideoTokenResponse'
2313 description: incorrect parameters
2315 description: video not found
2317 /api/v1/videos/{id}/studio/edit:
2319 summary: Create a studio task
2323 description: Create a task to edit a video (cut, add intro/outro etc)
2327 - $ref: '#/components/parameters/idOrUUID'
2331 application/x-www-form-urlencoded:
2333 $ref: '#/components/schemas/VideoStudioCreateTask'
2336 description: successful operation
2338 description: incorrect parameters
2340 description: video not found
2344 summary: List videos
2345 operationId: getVideos
2349 - $ref: '#/components/parameters/categoryOneOf'
2350 - $ref: '#/components/parameters/isLive'
2351 - $ref: '#/components/parameters/tagsOneOf'
2352 - $ref: '#/components/parameters/tagsAllOf'
2353 - $ref: '#/components/parameters/licenceOneOf'
2354 - $ref: '#/components/parameters/languageOneOf'
2355 - $ref: '#/components/parameters/nsfw'
2356 - $ref: '#/components/parameters/isLocal'
2357 - $ref: '#/components/parameters/include'
2358 - $ref: '#/components/parameters/privacyOneOf'
2359 - $ref: '#/components/parameters/hasHLSFiles'
2360 - $ref: '#/components/parameters/hasWebtorrentFiles'
2361 - $ref: '#/components/parameters/skipCount'
2362 - $ref: '#/components/parameters/start'
2363 - $ref: '#/components/parameters/count'
2364 - $ref: '#/components/parameters/videosSort'
2367 description: successful operation
2371 $ref: '#/components/schemas/VideoListResponse'
2373 /api/v1/videos/categories:
2375 summary: List available video categories
2376 operationId: getCategories
2381 description: successful operation
2390 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
2392 /api/v1/videos/licences:
2394 summary: List available video licences
2395 operationId: getLicences
2400 description: successful operation
2409 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
2411 /api/v1/videos/languages:
2413 summary: List available video languages
2414 operationId: getLanguages
2419 description: successful operation
2428 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
2430 /api/v1/videos/privacies:
2432 summary: List available video privacy policies
2433 operationId: getPrivacyPolicies
2438 description: successful operation
2447 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
2449 '/api/v1/videos/{id}':
2451 summary: Update a video
2452 operationId: putVideo
2458 - $ref: '#/components/parameters/idOrUUID'
2461 description: successful operation
2464 multipart/form-data:
2469 description: Video thumbnail file
2473 description: Video preview file
2477 $ref: '#/components/schemas/VideoCategorySet'
2479 $ref: '#/components/schemas/VideoLicenceSet'
2481 $ref: '#/components/schemas/VideoLanguageSet'
2483 $ref: '#/components/schemas/VideoPrivacySet'
2485 description: Video description
2488 description: Whether or not we wait transcoding before publish the video
2491 description: A text tell the audience how to support the video creator
2492 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2495 description: Whether or not this video contains sensitive content
2498 description: Video name
2503 description: Video tags (maximum 5 tags each between 2 and 30 characters)
2512 description: Enable or disable comments for this video
2515 description: Enable or disable downloading for this video
2517 originallyPublishedAt:
2518 description: Date when the content was originally published
2522 $ref: '#/components/schemas/VideoScheduledUpdate'
2525 contentType: image/jpeg
2527 contentType: image/jpeg
2529 summary: Get a video
2530 operationId: getVideo
2534 - $ref: '#/components/parameters/idOrUUID'
2537 description: successful operation
2541 $ref: '#/components/schemas/VideoDetails'
2543 summary: Delete a video
2544 operationId: delVideo
2550 - $ref: '#/components/parameters/idOrUUID'
2553 description: successful operation
2555 '/api/v1/videos/{id}/description':
2557 summary: Get complete video description
2558 operationId: getVideoDesc
2562 - $ref: '#/components/parameters/idOrUUID'
2565 description: successful operation
2574 **[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)**
2576 '/api/v1/videos/{id}/source':
2578 summary: Get video source file metadata
2579 operationId: getVideoSource
2583 - $ref: '#/components/parameters/idOrUUID'
2586 description: successful operation
2590 $ref: '#/components/schemas/VideoSource'
2592 '/api/v1/videos/{id}/views':
2594 summary: Notify user is watching a video
2595 description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.
2596 operationId: addView
2600 - $ref: '#/components/parameters/idOrUUID'
2605 $ref: '#/components/schemas/UserViewingVideo'
2609 description: successful operation
2611 '/api/v1/videos/{id}/watching':
2613 summary: Set watching progress of a video
2615 description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
2621 - $ref: '#/components/parameters/idOrUUID'
2626 $ref: '#/components/schemas/UserViewingVideo'
2630 description: successful operation
2632 '/api/v1/videos/{id}/stats/overall':
2634 summary: Get overall stats of a video
2640 - $ref: '#/components/parameters/idOrUUID'
2643 description: Filter stats by start date
2649 description: Filter stats by end date
2655 description: successful operation
2659 $ref: '#/components/schemas/VideoStatsOverall'
2661 '/api/v1/videos/{id}/stats/retention':
2663 summary: Get retention stats of a video
2669 - $ref: '#/components/parameters/idOrUUID'
2672 description: successful operation
2676 $ref: '#/components/schemas/VideoStatsRetention'
2678 '/api/v1/videos/{id}/stats/timeseries/{metric}':
2680 summary: Get timeserie stats of a video
2686 - $ref: '#/components/parameters/idOrUUID'
2691 description: The metric to get
2696 - 'aggregateWatchTime'
2699 description: Filter stats by start date
2705 description: Filter stats by end date
2711 description: successful operation
2715 $ref: '#/components/schemas/VideoStatsTimeserie'
2717 /api/v1/videos/upload:
2719 summary: Upload a video
2720 description: Uses a single request to upload a video.
2721 operationId: uploadLegacy
2729 description: successful operation
2733 $ref: '#/components/schemas/VideoUploadResponse'
2735 description: video didn't pass upload filter
2737 description: upload has timed out
2739 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
2741 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
2742 - `quota_reached` for quota limits whether daily or global
2744 X-File-Maximum-Size:
2748 description: Maximum file size for the video
2750 description: video type unsupported
2752 description: video unreadable
2755 multipart/form-data:
2757 $ref: '#/components/schemas/VideoUploadRequestLegacy'
2760 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
2762 contentType: image/jpeg
2764 contentType: image/jpeg
2769 USERNAME="<your_username>"
2770 PASSWORD="<your_password>"
2771 FILE_PATH="<your_file_path>"
2772 CHANNEL_ID="<your_channel_id>"
2774 API="https://peertube2.cpy.re/api/v1"
2777 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
2778 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
2779 token=$(curl -s "$API/users/token" \
2780 --data client_id="$client_id" \
2781 --data client_secret="$client_secret" \
2782 --data grant_type=password \
2783 --data username="$USERNAME" \
2784 --data password="$PASSWORD" \
2785 | jq -r ".access_token")
2788 curl -s "$API/videos/upload" \
2789 -H "Authorization: Bearer $token" \
2791 --form videofile=@"$FILE_PATH" \
2792 --form channelId=$CHANNEL_ID \
2795 /api/v1/videos/upload-resumable:
2797 summary: Initialize the resumable upload of a video
2798 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
2799 operationId: uploadResumableInit
2806 - name: X-Upload-Content-Length
2812 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2813 - name: X-Upload-Content-Type
2820 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2825 $ref: '#/components/schemas/VideoUploadRequestResumable'
2828 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2830 description: created
2836 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2842 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2844 Disambiguate via `type`:
2845 - `max_file_size_reached` for the absolute file size limit
2846 - `quota_reached` for quota limits whether daily or global
2848 description: video type unsupported
2850 summary: Send chunk for the resumable upload of a video
2851 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
2852 operationId: uploadResumable
2863 Created session id to proceed with. If you didn't send chunks in the last hour, it is
2864 not valid anymore and you need to initialize a new upload.
2867 - name: Content-Range
2871 example: bytes 0-262143/2469036
2874 Specifies the bytes in the file that the request is uploading.
2876 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2877 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2878 - name: Content-Length
2885 Size of the chunk that the request is sending.
2887 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2888 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2891 application/octet-stream:
2897 description: last chunk received
2905 $ref: '#/components/schemas/VideoUploadResponse'
2907 description: resume incomplete
2912 example: bytes=0-262143
2918 description: video didn't pass upload filter
2920 description: upload not found
2922 description: chunk doesn't match range
2924 description: video unreadable
2926 description: too many concurrent requests
2928 description: upload is already being processed
2935 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2936 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2937 operationId: uploadResumableCancel
2948 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2949 not valid anymore and the upload session has already been deleted with its data ;-)
2952 - name: Content-Length
2960 description: upload cancelled
2967 description: upload not found
2969 /api/v1/videos/imports:
2971 summary: Import a video
2972 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2973 operationId: importVideo
2981 multipart/form-data:
2983 $ref: '#/components/schemas/VideoCreateImport'
2986 contentType: application/x-bittorrent
2988 contentType: image/jpeg
2990 contentType: image/jpeg
2993 description: successful operation
2997 $ref: '#/components/schemas/VideoUploadResponse'
2999 description: '`magnetUri` or `targetUrl` or a torrent file missing'
3001 description: video didn't pass pre-import filter
3003 description: HTTP or Torrent/magnetURI import not enabled
3005 /api/v1/videos/imports/{id}/cancel:
3007 summary: Cancel video import
3008 description: Cancel a pending video import
3014 - $ref: '#/components/parameters/id'
3017 description: successful operation
3019 /api/v1/videos/imports/{id}:
3021 summary: Delete video import
3022 description: Delete ended video import
3028 - $ref: '#/components/parameters/id'
3031 description: successful operation
3033 /api/v1/videos/live:
3035 summary: Create a live
3036 operationId: addLive
3044 description: successful operation
3048 $ref: '#/components/schemas/VideoUploadResponse'
3050 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
3052 Disambiguate via `type`:
3053 - default type for a validation error
3054 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
3056 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
3058 Disambiguate via `type`:
3059 - `live_not_enabled` for a disabled live feature
3060 - `live_not_allowing_replay` for a disabled replay feature
3061 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
3062 - `max_user_lives_limit_reached` for the user concurrent live limit
3065 multipart/form-data:
3070 description: Channel id that will contain this live video
3075 description: User can stream multiple times in a permanent live
3078 description: User can select live latency mode if enabled by the instance
3079 $ref: '#/components/schemas/LiveVideoLatencyMode'
3081 description: Live video/replay thumbnail file
3085 description: Live video/replay preview file
3089 $ref: '#/components/schemas/VideoPrivacySet'
3091 $ref: '#/components/schemas/VideoCategorySet'
3093 $ref: '#/components/schemas/VideoLicenceSet'
3095 $ref: '#/components/schemas/VideoLanguageSet'
3097 description: Live video/replay description
3100 description: A text tell the audience how to support the creator
3101 example: Please support our work on https://soutenir.framasoft.org/en/ <3
3104 description: Whether or not this live video/replay contains sensitive content
3107 description: Live video/replay name
3112 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
3121 description: Enable or disable comments for this live video/replay
3124 description: Enable or disable downloading for the replay of this live video
3131 contentType: image/jpeg
3133 contentType: image/jpeg
3135 /api/v1/videos/live/{id}:
3137 summary: Get information about a live
3138 operationId: getLiveId
3145 - $ref: '#/components/parameters/idOrUUID'
3148 description: successful operation
3152 $ref: '#/components/schemas/LiveVideoResponse'
3154 summary: Update information about a live
3155 operationId: updateLiveId
3162 - $ref: '#/components/parameters/idOrUUID'
3167 $ref: '#/components/schemas/LiveVideoUpdate'
3170 description: successful operation
3172 description: bad parameters or trying to update a live that has already started
3174 description: trying to save replay of the live but saving replay is not enabled on the instance
3175 /api/v1/videos/live/{id}/sessions:
3177 summary: List live sessions
3178 description: List all sessions created in a particular live
3184 - $ref: '#/components/parameters/idOrUUID'
3187 description: successful operation
3199 $ref: '#/components/schemas/LiveVideoSessionResponse'
3200 /api/v1/videos/{id}/live-session:
3202 summary: Get live session of a replay
3203 description: If the video is a replay of a live, you can find the associated live session using this endpoint
3209 - $ref: '#/components/parameters/idOrUUID'
3212 description: successful operation
3216 $ref: '#/components/schemas/LiveVideoSessionResponse'
3218 /api/v1/users/me/abuses:
3220 summary: List my abuses
3221 operationId: getMyAbuses
3230 description: only list the report with this id
3236 $ref: '#/components/schemas/AbuseStateSet'
3237 - $ref: '#/components/parameters/abusesSort'
3238 - $ref: '#/components/parameters/start'
3239 - $ref: '#/components/parameters/count'
3242 description: successful operation
3254 $ref: '#/components/schemas/Abuse'
3258 summary: List abuses
3259 operationId: getAbuses
3269 description: only list the report with this id
3272 - name: predefinedReason
3274 description: predefined reason the listed reports should contain
3276 $ref: '#/components/schemas/PredefinedAbuseReasons'
3279 description: plain search that will match with video titles, reporter names and more
3285 $ref: '#/components/schemas/AbuseStateSet'
3286 - name: searchReporter
3288 description: only list reports of a specific reporter
3291 - name: searchReportee
3292 description: only list reports of a specific reportee
3298 description: only list reports of a specific video
3301 - name: searchVideoChannel
3303 description: only list reports of a specific video channel
3308 description: only list deleted or blocklisted videos
3316 description: only list account, comment or video reports
3323 - $ref: '#/components/parameters/start'
3324 - $ref: '#/components/parameters/count'
3325 - $ref: '#/components/parameters/abusesSort'
3328 description: successful operation
3340 $ref: '#/components/schemas/Abuse'
3342 summary: Report an abuse
3355 description: Reason why the user reports this video
3360 $ref: '#/components/schemas/PredefinedAbuseReasons'
3365 description: Video id to report
3367 - $ref: '#/components/schemas/Video/properties/id'
3371 description: Timestamp in the video that marks the beginning of the report
3376 description: Timestamp in the video that marks the ending of the report
3382 description: Comment id to report
3384 - $ref: '#/components/schemas/VideoComment/properties/id'
3389 description: Account id to report
3395 description: successful operation
3405 $ref: '#/components/schemas/id'
3407 description: incorrect request parameters
3409 '/api/v1/abuses/{abuseId}':
3411 summary: Update an abuse
3419 - $ref: '#/components/parameters/abuseId'
3427 $ref: '#/components/schemas/AbuseStateSet'
3430 description: Update the report comment visible only to the moderation team
3435 description: successful operation
3437 description: abuse not found
3441 summary: Delete an abuse
3447 - $ref: '#/components/parameters/abuseId'
3450 description: successful operation
3452 description: block not found
3454 '/api/v1/abuses/{abuseId}/messages':
3456 summary: List messages of an abuse
3462 - $ref: '#/components/parameters/abuseId'
3465 description: successful operation
3477 $ref: '#/components/schemas/AbuseMessage'
3479 summary: Add message to an abuse
3485 - $ref: '#/components/parameters/abuseId'
3494 description: Message to send
3502 description: successful operation
3504 description: incorrect request parameters
3506 '/api/v1/abuses/{abuseId}/messages/{abuseMessageId}':
3508 summary: Delete an abuse message
3514 - $ref: '#/components/parameters/abuseId'
3515 - $ref: '#/components/parameters/abuseMessageId'
3518 description: successful operation
3520 '/api/v1/videos/{id}/blacklist':
3522 summary: Block a video
3523 operationId: addVideoBlock
3531 - $ref: '#/components/parameters/idOrUUID'
3534 description: successful operation
3536 summary: Unblock a video by its id
3537 operationId: delVideoBlock
3545 - $ref: '#/components/parameters/idOrUUID'
3548 description: successful operation
3550 description: block not found
3552 /api/v1/videos/blacklist:
3556 summary: List video blocks
3557 operationId: getVideoBlocks
3566 list only blocks that match this type:
3570 - `2`: automatic block that needs review
3578 description: plain search that will match with video titles, and more
3581 - $ref: '#/components/parameters/start'
3582 - $ref: '#/components/parameters/count'
3583 - $ref: '#/components/parameters/blacklistsSort'
3586 description: successful operation
3598 $ref: '#/components/schemas/VideoBlacklist'
3600 /api/v1/videos/{id}/captions:
3602 summary: List captions of a video
3603 operationId: getVideoCaptions
3607 - $ref: '#/components/parameters/idOrUUID'
3610 description: successful operation
3622 $ref: '#/components/schemas/VideoCaption'
3624 /api/v1/videos/{id}/captions/{captionLanguage}:
3626 summary: Add or replace a video caption
3627 operationId: addVideoCaption
3634 - $ref: '#/components/parameters/idOrUUID'
3635 - $ref: '#/components/parameters/captionLanguage'
3638 multipart/form-data:
3643 description: The file to upload.
3648 contentType: text/vtt, application/x-subrip, text/plain
3651 description: successful operation
3653 description: video or language not found
3655 summary: Delete a video caption
3656 operationId: delVideoCaption
3663 - $ref: '#/components/parameters/idOrUUID'
3664 - $ref: '#/components/parameters/captionLanguage'
3667 description: successful operation
3669 description: video or language or caption for that language not found
3671 /api/v1/video-channels:
3673 summary: List video channels
3674 operationId: getVideoChannels
3678 - $ref: '#/components/parameters/start'
3679 - $ref: '#/components/parameters/count'
3680 - $ref: '#/components/parameters/sort'
3683 description: successful operation
3687 $ref: '#/components/schemas/VideoChannelList'
3689 summary: Create a video channel
3690 operationId: addVideoChannel
3697 description: successful operation
3707 $ref: '#/components/schemas/id'
3712 $ref: '#/components/schemas/VideoChannelCreate'
3714 '/api/v1/video-channels/{channelHandle}':
3716 summary: Get a video channel
3717 operationId: getVideoChannel
3721 - $ref: '#/components/parameters/channelHandle'
3724 description: successful operation
3728 $ref: '#/components/schemas/VideoChannel'
3730 summary: Update a video channel
3731 operationId: putVideoChannel
3737 - $ref: '#/components/parameters/channelHandle'
3740 description: successful operation
3745 $ref: '#/components/schemas/VideoChannelUpdate'
3747 summary: Delete a video channel
3748 operationId: delVideoChannel
3754 - $ref: '#/components/parameters/channelHandle'
3757 description: successful operation
3759 '/api/v1/video-channels/{channelHandle}/videos':
3761 summary: List videos of a video channel
3762 operationId: getVideoChannelVideos
3767 - $ref: '#/components/parameters/channelHandle'
3768 - $ref: '#/components/parameters/categoryOneOf'
3769 - $ref: '#/components/parameters/isLive'
3770 - $ref: '#/components/parameters/tagsOneOf'
3771 - $ref: '#/components/parameters/tagsAllOf'
3772 - $ref: '#/components/parameters/licenceOneOf'
3773 - $ref: '#/components/parameters/languageOneOf'
3774 - $ref: '#/components/parameters/nsfw'
3775 - $ref: '#/components/parameters/isLocal'
3776 - $ref: '#/components/parameters/include'
3777 - $ref: '#/components/parameters/privacyOneOf'
3778 - $ref: '#/components/parameters/hasHLSFiles'
3779 - $ref: '#/components/parameters/hasWebtorrentFiles'
3780 - $ref: '#/components/parameters/skipCount'
3781 - $ref: '#/components/parameters/start'
3782 - $ref: '#/components/parameters/count'
3783 - $ref: '#/components/parameters/videosSort'
3786 description: successful operation
3790 $ref: '#/components/schemas/VideoListResponse'
3792 '/api/v1/video-channels/{channelHandle}/followers':
3796 summary: 'List followers of a video channel'
3799 operationId: getVideoChannelFollowers
3801 - $ref: '#/components/parameters/channelHandle'
3802 - $ref: '#/components/parameters/start'
3803 - $ref: '#/components/parameters/count'
3804 - $ref: '#/components/parameters/followersSort'
3805 - $ref: '#/components/parameters/search'
3808 description: successful operation
3820 $ref: '#/components/schemas/Follow'
3822 '/api/v1/video-channels/{channelHandle}/avatar/pick':
3824 summary: Update channel avatar
3830 - $ref: '#/components/parameters/channelHandle'
3833 description: successful operation
3842 $ref: '#/components/schemas/ActorImage'
3844 description: image file too large
3846 X-File-Maximum-Size:
3850 description: Maximum file size for the avatar
3853 multipart/form-data:
3858 description: The file to upload.
3863 contentType: image/png, image/jpeg
3865 '/api/v1/video-channels/{channelHandle}/avatar':
3867 summary: Delete channel avatar
3873 - $ref: '#/components/parameters/channelHandle'
3876 description: successful operation
3878 '/api/v1/video-channels/{channelHandle}/banner/pick':
3880 summary: Update channel banner
3886 - $ref: '#/components/parameters/channelHandle'
3889 description: successful operation
3898 $ref: '#/components/schemas/ActorImage'
3900 description: image file too large
3902 X-File-Maximum-Size:
3906 description: Maximum file size for the banner
3909 multipart/form-data:
3914 description: The file to upload.
3919 contentType: image/png, image/jpeg
3921 '/api/v1/video-channels/{channelHandle}/banner':
3923 summary: Delete channel banner
3929 - $ref: '#/components/parameters/channelHandle'
3932 description: successful operation
3934 '/api/v1/video-channels/{channelHandle}/import-videos':
3936 summary: Import videos in channel
3937 description: Import a remote channel/playlist videos into a channel
3944 - $ref: '#/components/parameters/channelHandle'
3949 $ref: '#/components/schemas/ImportVideosInChannelCreate'
3952 description: successful operation
3954 '/api/v1/video-channel-syncs':
3956 summary: Create a synchronization for a video channel
3957 operationId: addVideoChannelSync
3966 $ref: '#/components/schemas/VideoChannelSyncCreate'
3969 description: successful operation
3976 $ref: "#/components/schemas/VideoChannelSync"
3978 '/api/v1/video-channel-syncs/{channelSyncId}':
3980 summary: Delete a video channel synchronization
3981 operationId: delVideoChannelSync
3987 - $ref: '#/components/parameters/channelSyncId'
3990 description: successful operation
3992 '/api/v1/video-channel-syncs/{channelSyncId}/sync':
3994 summary: Triggers the channel synchronization job, fetching all the videos from the remote channel
3995 operationId: triggerVideoChannelSync
4001 - $ref: '#/components/parameters/channelSyncId'
4004 description: successful operation
4007 /api/v1/video-playlists/privacies:
4009 summary: List available playlist privacy policies
4010 operationId: getPlaylistPrivacyPolicies
4015 description: successful operation
4024 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
4026 /api/v1/video-playlists:
4028 summary: List video playlists
4029 operationId: getPlaylists
4033 - $ref: '#/components/parameters/start'
4034 - $ref: '#/components/parameters/count'
4035 - $ref: '#/components/parameters/sort'
4038 description: successful operation
4050 $ref: '#/components/schemas/VideoPlaylist'
4052 summary: Create a video playlist
4053 description: If the video playlist is set as public, `videoChannelId` is mandatory.
4054 operationId: addPlaylist
4061 description: successful operation
4071 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4073 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
4075 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
4078 multipart/form-data:
4083 description: Video playlist display name
4088 description: Video playlist thumbnail file
4092 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4094 description: Video playlist description
4100 - $ref: '#/components/schemas/id'
4101 description: Video channel in which the playlist will be published
4106 contentType: image/jpeg
4108 /api/v1/video-playlists/{playlistId}:
4110 summary: Get a video playlist
4114 - $ref: '#/components/parameters/playlistId'
4117 description: successful operation
4121 $ref: '#/components/schemas/VideoPlaylist'
4123 summary: Update a video playlist
4124 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
4131 description: successful operation
4133 - $ref: '#/components/parameters/playlistId'
4136 multipart/form-data:
4141 description: Video playlist display name
4146 description: Video playlist thumbnail file
4150 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4152 description: Video playlist description
4156 - $ref: '#/components/schemas/id'
4157 description: Video channel in which the playlist will be published
4160 contentType: image/jpeg
4162 summary: Delete a video playlist
4168 - $ref: '#/components/parameters/playlistId'
4171 description: successful operation
4173 /api/v1/video-playlists/{playlistId}/videos:
4175 summary: 'List videos of a playlist'
4176 operationId: getVideoPlaylistVideos
4181 - $ref: '#/components/parameters/playlistId'
4182 - $ref: '#/components/parameters/start'
4183 - $ref: '#/components/parameters/count'
4186 description: successful operation
4190 $ref: '#/components/schemas/VideoListResponse'
4192 summary: Add a video in a playlist
4193 operationId: addVideoPlaylistVideo
4200 - $ref: '#/components/parameters/playlistId'
4203 description: successful operation
4209 videoPlaylistElement:
4223 - $ref: '#/components/schemas/Video/properties/uuid'
4224 - $ref: '#/components/schemas/Video/properties/id'
4225 description: Video to add in the playlist
4229 description: Start the video at this specific timestamp
4233 description: Stop the video at this specific timestamp
4237 /api/v1/video-playlists/{playlistId}/videos/reorder:
4239 summary: 'Reorder a playlist'
4240 operationId: reorderVideoPlaylist
4246 - $ref: '#/components/parameters/playlistId'
4249 description: successful operation
4258 description: 'Start position of the element to reorder'
4260 insertAfterPosition:
4262 description: 'New position for the block to reorder, to add the block before the first element'
4266 description: 'How many element from `startPosition` to reorder'
4270 - insertAfterPosition
4272 /api/v1/video-playlists/{playlistId}/videos/{playlistElementId}:
4274 summary: Update a playlist element
4275 operationId: putVideoPlaylistVideo
4281 - $ref: '#/components/parameters/playlistId'
4282 - $ref: '#/components/parameters/playlistElementId'
4285 description: successful operation
4295 description: Start the video at this specific timestamp
4299 description: Stop the video at this specific timestamp
4301 summary: Delete an element from a playlist
4302 operationId: delVideoPlaylistVideo
4308 - $ref: '#/components/parameters/playlistId'
4309 - $ref: '#/components/parameters/playlistElementId'
4312 description: successful operation
4314 '/api/v1/users/me/video-playlists/videos-exist':
4316 summary: Check video exists in my playlists
4325 description: The video ids to check
4329 $ref: '#/components/schemas/Video/properties/id'
4332 description: successful operation
4354 '/api/v1/accounts/{name}/video-channels':
4356 summary: List video channels of an account
4361 - $ref: '#/components/parameters/name'
4364 description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
4367 - $ref: '#/components/parameters/start'
4368 - $ref: '#/components/parameters/count'
4369 - $ref: '#/components/parameters/sort'
4372 description: successful operation
4376 $ref: '#/components/schemas/VideoChannelList'
4378 '/api/v1/accounts/{name}/video-channel-syncs':
4380 summary: List the synchronizations of video channels of an account
4386 - $ref: '#/components/parameters/name'
4387 - $ref: '#/components/parameters/start'
4388 - $ref: '#/components/parameters/count'
4389 - $ref: '#/components/parameters/sort'
4392 description: successful operation
4396 $ref: '#/components/schemas/VideoChannelSyncList'
4398 '/api/v1/accounts/{name}/ratings':
4400 summary: List ratings of an account
4406 - $ref: '#/components/parameters/name'
4407 - $ref: '#/components/parameters/start'
4408 - $ref: '#/components/parameters/count'
4409 - $ref: '#/components/parameters/sort'
4413 description: Optionally filter which ratings to retrieve
4421 description: successful operation
4427 $ref: '#/components/schemas/VideoRating'
4429 '/api/v1/videos/{id}/comment-threads':
4431 summary: List threads of a video
4435 - $ref: '#/components/parameters/idOrUUID'
4436 - $ref: '#/components/parameters/start'
4437 - $ref: '#/components/parameters/count'
4438 - $ref: '#/components/parameters/commentsSort'
4441 description: successful operation
4445 $ref: '#/components/schemas/CommentThreadResponse'
4447 summary: Create a thread
4453 - $ref: '#/components/parameters/idOrUUID'
4456 description: successful operation
4460 $ref: '#/components/schemas/CommentThreadPostResponse'
4462 description: video does not exist
4471 - $ref: '#/components/schemas/VideoComment/properties/text'
4477 '/api/v1/videos/{id}/comment-threads/{threadId}':
4479 summary: Get a thread
4483 - $ref: '#/components/parameters/idOrUUID'
4484 - $ref: '#/components/parameters/threadId'
4487 description: successful operation
4491 $ref: '#/components/schemas/VideoCommentThreadTree'
4493 '/api/v1/videos/{id}/comments/{commentId}':
4495 summary: Reply to a thread of a video
4501 - $ref: '#/components/parameters/idOrUUID'
4502 - $ref: '#/components/parameters/commentId'
4505 description: successful operation
4509 $ref: '#/components/schemas/CommentThreadPostResponse'
4511 description: thread or video does not exist
4520 - $ref: '#/components/schemas/VideoComment/properties/text'
4526 summary: Delete a comment or a reply
4532 - $ref: '#/components/parameters/idOrUUID'
4533 - $ref: '#/components/parameters/commentId'
4536 description: successful operation
4538 description: cannot remove comment of another user
4540 description: comment or video does not exist
4542 description: comment is already deleted
4544 '/api/v1/videos/{id}/rate':
4546 summary: Like/dislike a video
4552 - $ref: '#/components/parameters/idOrUUID'
4568 description: successful operation
4570 description: video does not exist
4572 '/api/v1/videos/{id}/hls':
4574 summary: Delete video HLS files
4580 operationId: delVideoHLS
4582 - $ref: '#/components/parameters/idOrUUID'
4585 description: successful operation
4587 description: video does not exist
4588 '/api/v1/videos/{id}/webtorrent':
4590 summary: Delete video WebTorrent files
4596 operationId: delVideoWebTorrent
4598 - $ref: '#/components/parameters/idOrUUID'
4601 description: successful operation
4603 description: video does not exist
4605 '/api/v1/videos/{id}/transcoding':
4607 summary: Create a transcoding job
4613 operationId: createVideoTranscoding
4615 - $ref: '#/components/parameters/idOrUUID'
4631 description: successful operation
4633 description: video does not exist
4635 /api/v1/search/videos:
4639 summary: Search videos
4640 operationId: searchVideos
4645 allowEmptyValue: false
4647 String to search. If the user can make a remote URI search, and the string is an URI then the
4648 PeerTube instance will fetch the remote object and add it to its database. Then,
4649 you can use the REST API to fetch the complete video information and interact with it.
4652 - $ref: '#/components/parameters/categoryOneOf'
4653 - $ref: '#/components/parameters/isLive'
4654 - $ref: '#/components/parameters/tagsOneOf'
4655 - $ref: '#/components/parameters/tagsAllOf'
4656 - $ref: '#/components/parameters/licenceOneOf'
4657 - $ref: '#/components/parameters/languageOneOf'
4658 - $ref: '#/components/parameters/nsfw'
4659 - $ref: '#/components/parameters/isLocal'
4660 - $ref: '#/components/parameters/include'
4661 - $ref: '#/components/parameters/privacyOneOf'
4662 - $ref: '#/components/parameters/uuids'
4663 - $ref: '#/components/parameters/hasHLSFiles'
4664 - $ref: '#/components/parameters/hasWebtorrentFiles'
4665 - $ref: '#/components/parameters/skipCount'
4666 - $ref: '#/components/parameters/start'
4667 - $ref: '#/components/parameters/count'
4668 - $ref: '#/components/parameters/searchTarget'
4669 - $ref: '#/components/parameters/videosSearchSort'
4672 description: Get videos that are published after this date
4678 description: Get videos that are published before this date
4682 - name: originallyPublishedStartDate
4684 description: Get videos that are originally published after this date
4688 - name: originallyPublishedEndDate
4690 description: Get videos that are originally published before this date
4696 description: Get videos that have this minimum duration
4701 description: Get videos that have this maximum duration
4705 'searchTarget === search-index':
4706 $ref: '#/components/callbacks/searchIndex'
4709 description: successful operation
4713 $ref: '#/components/schemas/VideoListResponse'
4715 description: search index unavailable
4717 /api/v1/search/video-channels:
4721 summary: Search channels
4722 operationId: searchChannels
4728 String to search. If the user can make a remote URI search, and the string is an URI then the
4729 PeerTube instance will fetch the remote object and add it to its database. Then,
4730 you can use the REST API to fetch the complete channel information and interact with it.
4733 - $ref: '#/components/parameters/start'
4734 - $ref: '#/components/parameters/count'
4735 - $ref: '#/components/parameters/searchTarget'
4736 - $ref: '#/components/parameters/sort'
4738 'searchTarget === search-index':
4739 $ref: '#/components/callbacks/searchIndex'
4742 description: successful operation
4746 $ref: '#/components/schemas/VideoChannelList'
4748 description: search index unavailable
4750 /api/v1/search/video-playlists:
4754 summary: Search playlists
4755 operationId: searchPlaylists
4761 String to search. If the user can make a remote URI search, and the string is an URI then the
4762 PeerTube instance will fetch the remote object and add it to its database. Then,
4763 you can use the REST API to fetch the complete playlist information and interact with it.
4766 - $ref: '#/components/parameters/start'
4767 - $ref: '#/components/parameters/count'
4768 - $ref: '#/components/parameters/searchTarget'
4769 - $ref: '#/components/parameters/sort'
4771 'searchTarget === search-index':
4772 $ref: '#/components/callbacks/searchIndex'
4775 description: successful operation
4787 $ref: '#/components/schemas/VideoPlaylist'
4789 description: search index unavailable
4791 /api/v1/blocklist/status:
4796 summary: Get block status of accounts/hosts
4801 description: 'Check if these accounts are blocked'
4802 example: [ 'goofy@example.com', 'donald@example.com' ]
4810 description: 'Check if these hosts are blocked'
4811 example: [ 'example.com' ]
4818 description: successful operation
4822 $ref: '#/components/schemas/BlockStatus'
4824 /api/v1/server/blocklist/accounts:
4828 summary: List account blocks
4833 - $ref: '#/components/parameters/start'
4834 - $ref: '#/components/parameters/count'
4835 - $ref: '#/components/parameters/sort'
4838 description: successful operation
4842 summary: Block an account
4854 example: chocobozzz@example.org
4855 description: account to block, in the form `username@domain`
4860 description: successful operation
4862 description: self-blocking forbidden
4864 '/api/v1/server/blocklist/accounts/{accountName}':
4868 summary: Unblock an account by its handle
4876 description: account to unblock, in the form `username@domain`
4881 description: successful operation
4883 description: account or account block does not exist
4885 /api/v1/server/blocklist/servers:
4889 summary: List server blocks
4894 - $ref: '#/components/parameters/start'
4895 - $ref: '#/components/parameters/count'
4896 - $ref: '#/components/parameters/sort'
4899 description: successful operation
4903 summary: Block a server
4916 description: server domain to block
4921 description: successful operation
4923 description: self-blocking forbidden
4925 '/api/v1/server/blocklist/servers/{host}':
4929 summary: Unblock a server by its domain
4937 description: server domain to unblock
4943 description: successful operation
4945 description: account block does not exist
4947 /api/v1/server/redundancy/{host}:
4950 - Instance Redundancy
4951 summary: Update a server redundancy policy
4959 description: server domain to mirror
4971 description: allow mirroring of the host's local videos
4976 description: successful operation
4978 description: server is not already known
4980 /api/v1/server/redundancy/videos:
4984 summary: List videos being mirrored
4985 operationId: getMirroredVideos
4993 description: direction of the mirror
4999 - $ref: '#/components/parameters/start'
5000 - $ref: '#/components/parameters/count'
5001 - $ref: '#/components/parameters/videoRedundanciesSort'
5004 description: successful operation
5010 $ref: '#/components/schemas/VideoRedundancy'
5014 summary: Mirror a video
5015 operationId: putMirroredVideo
5026 $ref: '#/components/schemas/Video/properties/id'
5031 description: successful operation
5033 description: cannot mirror a local video
5035 description: video does not exist
5037 description: video is already mirrored
5039 /api/v1/server/redundancy/videos/{redundancyId}:
5043 summary: Delete a mirror done on a video
5044 operationId: delMirroredVideo
5049 - name: redundancyId
5052 description: id of an existing redundancy on a video
5057 description: successful operation
5059 description: video redundancy not found
5061 /api/v1/server/stats:
5065 summary: Get instance stats
5066 description: Get instance public statistics. This endpoint is cached.
5067 operationId: getInstanceStats
5070 description: successful operation
5074 $ref: '#/components/schemas/ServerStats'
5076 /api/v1/server/logs/client:
5080 summary: Send client log
5081 operationId: sendClientLog
5086 $ref: '#/components/schemas/SendClientLog'
5089 description: successful operation
5091 /api/v1/server/logs:
5095 summary: Get instance logs
5096 operationId: getInstanceLogs
5102 description: successful operation
5110 /api/v1/server/audit-logs:
5114 summary: Get instance audit logs
5115 operationId: getInstanceAuditLogs
5121 description: successful operation
5133 summary: List plugins
5134 operationId: getPlugins
5147 - $ref: '#/components/parameters/start'
5148 - $ref: '#/components/parameters/count'
5149 - $ref: '#/components/parameters/sort'
5152 description: successful operation
5156 $ref: '#/components/schemas/PluginResponse'
5158 /api/v1/plugins/available:
5162 summary: List available plugins
5163 operationId: getAvailablePlugins
5176 - name: currentPeerTubeEngine
5180 - $ref: '#/components/parameters/start'
5181 - $ref: '#/components/parameters/count'
5182 - $ref: '#/components/parameters/sort'
5185 description: successful operation
5189 $ref: '#/components/schemas/PluginResponse'
5191 description: plugin index unavailable
5193 /api/v1/plugins/install:
5197 summary: Install a plugin
5198 operationId: addPlugin
5211 example: peertube-plugin-auth-ldap
5214 additionalProperties: false
5221 additionalProperties: false
5224 description: successful operation
5226 description: should have either `npmName` or `path` set
5228 /api/v1/plugins/update:
5232 summary: Update a plugin
5233 operationId: updatePlugin
5246 example: peertube-plugin-auth-ldap
5249 additionalProperties: false
5256 additionalProperties: false
5259 description: successful operation
5261 description: should have either `npmName` or `path` set
5263 description: existing plugin not found
5265 /api/v1/plugins/uninstall:
5269 summary: Uninstall a plugin
5270 operationId: uninstallPlugin
5282 description: name of the plugin/theme in its package.json
5283 example: peertube-plugin-auth-ldap
5288 description: successful operation
5290 description: existing plugin not found
5292 /api/v1/plugins/{npmName}:
5296 summary: Get a plugin
5297 operationId: getPlugin
5302 - $ref: '#/components/parameters/npmName'
5305 description: successful operation
5309 $ref: '#/components/schemas/Plugin'
5311 description: plugin not found
5313 /api/v1/plugins/{npmName}/settings:
5317 summary: Set a plugin's settings
5322 - $ref: '#/components/parameters/npmName'
5331 additionalProperties: true
5334 description: successful operation
5336 description: plugin not found
5338 /api/v1/plugins/{npmName}/public-settings:
5342 summary: Get a plugin's public settings
5344 - $ref: '#/components/parameters/npmName'
5347 description: successful operation
5352 additionalProperties: true
5354 description: plugin not found
5356 /api/v1/plugins/{npmName}/registered-settings:
5360 summary: Get a plugin's registered settings
5365 - $ref: '#/components/parameters/npmName'
5368 description: successful operation
5373 additionalProperties: true
5375 description: plugin not found
5377 /api/v1/metrics/playback:
5379 summary: Create playback metrics
5380 description: These metrics are exposed by OpenTelemetry metrics exporter if enabled.
5387 $ref: '#/components/schemas/PlaybackMetricCreate'
5390 description: successful operation
5393 - url: 'https://peertube2.cpy.re'
5394 description: Live Test Server (live data - latest nightly version)
5395 - url: 'https://peertube3.cpy.re'
5396 description: Live Test Server (live data - latest RC version)
5397 - url: 'https://peertube.cpy.re'
5398 description: Live Test Server (live data - stable version)
5405 description: Offset used to paginate results
5413 description: "Number of items to return"
5423 description: Sort column
5431 description: Plain text search, applied to various parts of the model depending on endpoint
5439 If the administrator enabled search index support, you can override the default search target.
5442 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
5443 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
5444 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
5445 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
5446 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
5447 * 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
5448 the data from the origin instance API
5471 Sort videos by criteria (prefixing with `-` means `DESC` order):
5472 * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
5473 * `best` - Same than `hot`, but also takes into account user video history
5474 * `trending` - Sort videos by recent views ("recent" is defined by the admin)
5475 * `views` - Sort videos using their `views` counter
5476 * `publishedAt` - Sort by video publication date (when it became publicly available)
5482 Sort videos by criteria (prefixing with `-` means `DESC` order):
5497 description: Sort comments by criteria
5507 description: Sort blocklists by criteria
5523 description: Plain text search that will match with user usernames or emails
5530 description: Filter results down to (un)banned users
5537 description: Sort users by criteria
5548 description: Sort abuses by criteria
5555 videoRedundanciesSort:
5559 description: Sort abuses by criteria
5568 description: Sort followers by criteria
5578 description: The username or handle of the account
5581 example: chocobozzz | chocobozzz@example.org
5586 description: Entity id
5588 $ref: '#/components/schemas/id'
5590 name: registrationId
5593 description: Registration ID
5595 $ref: '#/components/schemas/id'
5600 description: The object id, uuid or short uuid
5603 - $ref: '#/components/schemas/id'
5604 - $ref: '#/components/schemas/UUIDv4'
5605 - $ref: '#/components/schemas/shortUUID'
5610 description: Playlist id
5612 $ref: '#/components/schemas/VideoPlaylist/properties/id'
5614 name: playlistElementId
5617 description: Playlist element id
5619 $ref: '#/components/schemas/id'
5624 description: Abuse id
5626 $ref: '#/components/schemas/Abuse/properties/id'
5628 name: abuseMessageId
5631 description: Abuse message id
5633 $ref: '#/components/schemas/AbuseMessage/properties/id'
5635 name: captionLanguage
5638 description: The caption language
5640 $ref: '#/components/schemas/VideoLanguageSet'
5645 description: The video channel handle
5648 example: my_username | my_username@example.com
5653 description: Channel Sync id
5655 $ref: '#/components/schemas/Abuse/properties/id'
5657 name: subscriptionHandle
5660 description: The subscription handle
5663 example: my_username | my_username@example.com
5668 description: The thread id (root comment id)
5675 description: The comment id
5677 $ref: '#/components/schemas/VideoComment/properties/id'
5682 description: whether or not the video is a live
5689 description: category id of the video (see [/videos/categories](#operation/getCategories))
5692 - $ref: '#/components/schemas/VideoCategorySet'
5695 $ref: '#/components/schemas/VideoCategorySet'
5702 description: tag(s) of the video
5716 description: tag(s) of the video, where all should be present in the video
5729 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
5732 - $ref: '#/components/schemas/VideoLanguageSet'
5735 $ref: '#/components/schemas/VideoLanguageSet'
5742 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5745 - $ref: '#/components/schemas/VideoLicenceSet'
5748 $ref: '#/components/schemas/VideoLicenceSet'
5755 description: if you don't need the `total` in the response
5766 description: whether to include nsfw videos, if any
5778 description: '**PeerTube >= 4.0** Display only local or remote videos'
5785 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
5787 name: hasWebtorrentFiles
5792 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
5798 $ref: '#/components/schemas/VideoPrivacySet'
5799 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
5807 description: 'Find videos with specific UUIDs'
5821 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
5825 - `1` NOT_PUBLISHED_STATE
5836 description: list of uris to check if each is part of the user subscriptions
5846 description: name of the plugin/theme on npmjs.com or in its package.json
5849 example: peertube-plugin-auth-ldap
5854 description: job type
5858 - activitypub-follow
5859 - activitypub-http-broadcast
5860 - activitypub-http-fetcher
5861 - activitypub-http-unicast
5866 - videos-views-stats
5867 - activitypub-refresher
5870 - video-channel-import
5894 description: Filename
5898 name: videoFileToken
5901 description: Video file token [generated](#operation/requestVideoToken) by PeerTube so you don't need to provide an OAuth token in the request header.
5904 reinjectVideoFileToken:
5905 name: reinjectVideoFileToken
5908 description: Ask the server to reinject videoFileToken in URLs in m3u8 playlist
5915 Authenticating via OAuth requires the following steps:
5916 - Have an activated account
5917 - [Generate] an access token for that account at `/api/v1/users/token`.
5918 - Make requests with the *Authorization: Bearer <token\>* header
5919 - Profit, depending on the role assigned to the account
5921 Note that the __access token is valid for 1 day__ and is given
5922 along with a __refresh token valid for 2 weeks__.
5924 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5928 tokenUrl: /api/v1/users/token
5931 moderator: Moderator scope
5934 # Reusable core properties
5942 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5943 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5948 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5949 example: 2y84q2MQUMWPbiEcxNXMgC
5952 description: immutable name of the user, used to find or mention its actor
5954 pattern: '/^[a-z0-9._]+$/'
5959 description: immutable name of the channel, used to interact with its actor
5960 example: framasoft_videos
5961 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5972 description: category id of the video (see [/videos/categories](#operation/getCategories))
5974 VideoConstantNumber-Category:
5977 $ref: '#/components/schemas/VideoCategorySet'
5980 example: Science & Technology
5984 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5986 VideoConstantNumber-Licence:
5989 $ref: '#/components/schemas/VideoLicenceSet'
5992 example: Attribution - Share Alike
5996 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5998 VideoConstantString-Language:
6001 $ref: '#/components/schemas/VideoLanguageSet'
6006 VideoPlaylistPrivacySet:
6012 description: Video playlist privacy policy (see [/video-playlists/privacies])
6013 VideoPlaylistPrivacyConstant:
6016 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
6020 VideoPlaylistTypeSet:
6025 description: The video playlist type (Regular = `1`, Watch Later = `2`)
6026 VideoPlaylistTypeConstant:
6029 $ref: '#/components/schemas/VideoPlaylistTypeSet'
6040 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
6041 VideoPrivacyConstant:
6044 $ref: '#/components/schemas/VideoPrivacySet'
6052 additionalProperties:
6053 x-additionalPropertiesName: account
6062 additionalProperties:
6063 x-additionalPropertiesName: host
6084 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
6091 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
6094 LiveVideoLatencyMode:
6100 description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
6121 - `4`: Waiting for live stream
6123 - `6`: To move to an external storage (object storage...)
6124 - `7`: Transcoding failed
6125 - `8`: Moving to an external storage failed
6126 - `9`: To edit using studio edition feature
6136 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
6140 $ref: '#/components/schemas/AbuseStateSet'
6143 AbusePredefinedReasons:
6156 example: [spamOrMisleading]
6161 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
6163 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
6165 VideoResolutionConstant:
6166 description: resolutions and their labels for the video
6169 $ref: '#/components/schemas/VideoResolutionSet'
6173 VideoScheduledUpdate:
6176 $ref: '#/components/schemas/VideoPrivacySet'
6180 description: When to update the video
6200 $ref: '#/components/schemas/ActorImage'
6201 VideoChannelSummary:
6204 $ref: '#/components/schemas/id'
6218 $ref: '#/components/schemas/ActorImage'
6232 - $ref: '#/components/schemas/Video'
6237 $ref: '#/components/schemas/id'
6241 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
6242 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6244 $ref: '#/components/schemas/VideoResolutionConstant'
6247 description: Video file size in bytes
6250 description: Direct URL of the torrent file
6254 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
6258 description: Direct URL of the video
6262 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
6266 description: Frames per second of the video file
6270 description: URL dereferencing the output of ffprobe on the file
6271 VideoStreamingPlaylists:
6276 $ref: '#/components/schemas/id'
6284 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
6285 VideoStreamingPlaylists-HLS:
6296 Video files associated to this playlist.
6298 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
6300 $ref: '#/components/schemas/VideoFile'
6312 $ref: '#/components/schemas/Video/properties/id'
6314 $ref: '#/components/schemas/Video/properties/uuid'
6316 $ref: '#/components/schemas/Video/properties/name'
6320 description: object id for the video
6322 - $ref: '#/components/schemas/id'
6324 description: universal identifier for the video, that can be used across instances
6326 - $ref: '#/components/schemas/UUIDv4'
6329 - $ref: '#/components/schemas/shortUUID'
6335 example: 2017-10-01T10:52:46.396Z
6336 description: time at which the video object was first drafted
6340 example: 2018-10-01T10:52:46.396Z
6341 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
6345 example: 2021-05-04T08:01:01.502Z
6346 description: last time the video's metadata was modified
6347 originallyPublishedAt:
6350 example: 2010-10-01T10:52:46.396Z
6351 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
6354 - $ref: '#/components/schemas/VideoConstantNumber-Category'
6355 description: category in which the video is classified
6358 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
6359 description: licence under which the video is distributed
6362 - $ref: '#/components/schemas/VideoConstantString-Language'
6363 description: main language used in the video
6366 - $ref: '#/components/schemas/VideoPrivacyConstant'
6367 description: privacy policy used to distribute the video
6371 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
6372 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
6376 truncated description of the video, written in Markdown.
6377 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
6382 description: duration of the video in seconds
6387 description: title of the video
6388 example: What is PeerTube?
6393 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
6396 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
6399 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
6416 - $ref: '#/components/schemas/VideoStateConstant'
6417 description: represents the internal state of the video processing within the PeerTube instance
6421 - $ref: '#/components/schemas/VideoScheduledUpdate'
6429 $ref: '#/components/schemas/AccountSummary'
6431 $ref: '#/components/schemas/VideoChannelSummary'
6440 - $ref: '#/components/schemas/Video'
6445 description: If the video is a live, you have the amount of current viewers
6448 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
6449 description: path at which to get the full description of maximum `10000` characters
6452 description: A text tell the audience how to support the video creator
6453 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6457 $ref: '#/components/schemas/VideoChannel'
6459 $ref: '#/components/schemas/Account'
6461 example: [flowers, gardening]
6479 - https://peertube2.cpy.re/tracker/announce
6480 - wss://peertube2.cpy.re/tracker/socket
6484 $ref: '#/components/schemas/VideoFile'
6486 WebTorrent/raw video files. If WebTorrent is disabled on the server:
6488 - field will be empty
6489 - video files will be found in `streamingPlaylists[].files` field
6493 $ref: '#/components/schemas/VideoStreamingPlaylists'
6495 HLS playlists/manifest files. If HLS is disabled on the server:
6497 - field will be empty
6498 - video files will be found in `files` field
6499 FileRedundancyInformation:
6502 $ref: '#/components/schemas/id'
6527 $ref: '#/components/schemas/id'
6534 $ref: '#/components/schemas/UUIDv4'
6541 $ref: '#/components/schemas/FileRedundancyInformation'
6545 $ref: '#/components/schemas/FileRedundancyInformation'
6546 VideoImportStateConstant:
6554 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
6561 additionalProperties: false
6565 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
6566 required: [targetUrl]
6569 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6570 required: [magnetUri]
6573 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
6574 required: [torrentfile]
6575 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6584 - $ref: '#/components/schemas/id'
6588 description: remote URL where to find the import's source video
6589 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
6593 description: magnet URI allowing to resolve the import's source video
6594 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6599 description: Torrent file containing only the video file
6606 - $ref: '#/components/schemas/VideoImportStateConstant'
6622 - $ref: '#/components/schemas/Video'
6632 $ref: '#/components/schemas/VideoImport'
6636 $ref: '#/components/schemas/id'
6639 example: The video is a spam
6643 $ref: '#/components/schemas/AbusePredefinedReasons'
6645 $ref: '#/components/schemas/Account'
6647 $ref: '#/components/schemas/AbuseStateConstant'
6650 example: Decided to ban the server since it spams us regularly
6654 $ref: '#/components/schemas/VideoInfo'
6661 $ref: '#/components/schemas/id'
6672 $ref: '#/components/schemas/AccountSummary'
6676 $ref: '#/components/schemas/id'
6678 $ref: '#/components/schemas/Video/properties/id'
6690 $ref: '#/components/schemas/UUIDv4'
6708 $ref: '#/components/schemas/id'
6710 $ref: '#/components/schemas/UUIDv4'
6713 - $ref: '#/components/schemas/shortUUID'
6736 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
6738 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
6740 $ref: '#/components/schemas/AccountSummary'
6742 $ref: '#/components/schemas/VideoChannelSummary'
6746 $ref: '#/components/schemas/id'
6753 description: Text of the comment
6755 example: This video is wonderful!
6757 $ref: '#/components/schemas/id'
6761 - $ref: '#/components/schemas/id'
6763 $ref: '#/components/schemas/Video/properties/id'
6778 totalRepliesFromVideoAuthor:
6785 $ref: '#/components/schemas/Account'
6786 VideoCommentThreadTree:
6789 $ref: '#/components/schemas/VideoComment'
6793 $ref: '#/components/schemas/VideoCommentThreadTree'
6797 $ref: '#/components/schemas/VideoConstantString-Language'
6819 $ref: '#/components/schemas/id'
6830 $ref: '#/components/schemas/ActorImage'
6834 $ref: '#/components/schemas/id'
6839 description: immutable name of the actor, used to find or mention it
6841 - $ref: '#/components/schemas/username'
6845 description: server on which the actor is resident
6846 hostRedundancyAllowed:
6848 description: whether this actor's host allows redundancy of its videos
6852 description: number of actors subscribed to by this actor, as seen by this instance
6856 description: number of followers of this actor, as seen by this instance
6865 - $ref: '#/components/schemas/Actor'
6868 description: object id for the user tied to this account
6870 - $ref: '#/components/schemas/User/properties/id'
6873 description: editable name of the account, displayed in its representations
6878 description: text or bio displayed on the account's profile
6886 description: timestamp within the video, in seconds
6893 Event since last viewing call:
6894 * `seek` - If the user seeked the video
6917 VideoStatsRetention:
6929 VideoStatsTimeserie:
7006 allowedForCurrentIP:
7008 requiresEmailVerification:
7026 $ref: '#/components/schemas/VideoResolutionSet'
7043 videoChannelSynchronization:
7116 example: 16810141515
7157 description: URL of the current user page
7164 description: Stack trace of the error if there is one
7167 description: User agent of the web browser that sends the message
7170 description: Additional information regarding this log
7180 totalDailyActiveUsers:
7182 totalWeeklyActiveUsers:
7184 totalMonthlyActiveUsers:
7188 totalLocalVideoViews:
7190 description: Total video views made on the instance
7191 totalLocalVideoComments:
7193 description: Total comments made by local users
7194 totalLocalVideoFilesSize:
7200 totalLocalVideoChannels:
7202 totalLocalDailyActiveVideoChannels:
7204 totalLocalWeeklyActiveVideoChannels:
7206 totalLocalMonthlyActiveVideoChannels:
7208 totalLocalPlaylists:
7210 totalInstanceFollowers:
7212 totalInstanceFollowing:
7229 totalActivityPubMessagesProcessed:
7231 totalActivityPubMessagesSuccesses:
7233 totalActivityPubMessagesErrors:
7236 activityPubMessagesProcessedPerSecond:
7238 totalActivityPubMessagesWaiting:
7315 requiresEmailVerification:
7330 description: Settings that apply to new users, if registration is enabled
7334 example: 16810141515
7340 description: Settings pertaining to transcoding jobs
7344 allowAdditionalExtensions:
7346 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
7349 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
7352 description: Amount of threads used by ffmpeg for 1 transcoding job
7355 description: Amount of transcoding jobs to execute in parallel
7361 New profiles can be added by plugins ; available in core PeerTube: 'default'.
7364 description: Resolutions to transcode _new videos_ to
7386 description: WebTorrent-specific settings
7392 description: HLS-specific settings
7412 video_channel_synchronization:
7447 $ref: '#/components/schemas/id'
7449 $ref: '#/components/schemas/Actor'
7451 $ref: '#/components/schemas/Actor'
7454 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
7467 PredefinedAbuseReasons:
7468 description: Reason categories that help triage reports
7486 $ref: '#/components/schemas/id'
7498 - activitypub-http-unicast
7499 - activitypub-http-broadcast
7500 - activitypub-http-fetcher
7501 - activitypub-follow
7506 - videos-views-stats
7507 - activitypub-refresher
7509 - video-channel-import
7512 additionalProperties: true
7515 additionalProperties: true
7531 $ref: '#/components/schemas/id'
7536 $ref: '#/components/schemas/id'
7537 VideoUploadRequestCommon:
7540 description: Video name
7542 example: What is PeerTube?
7546 description: Channel id that will contain this video
7551 $ref: '#/components/schemas/VideoPrivacySet'
7553 $ref: '#/components/schemas/VideoCategorySet'
7555 $ref: '#/components/schemas/VideoLicenceSet'
7557 $ref: '#/components/schemas/VideoLanguageSet'
7559 description: Video description
7562 **[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)**
7564 description: Whether or not we wait transcoding before publish the video
7567 description: A text tell the audience how to support the video creator
7568 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7571 description: Whether or not this video contains sensitive content
7574 description: Video tags (maximum 5 tags each between 2 and 30 characters)
7587 description: Enable or disable comments for this video
7590 description: Enable or disable downloading for this video
7592 originallyPublishedAt:
7593 description: Date when the content was originally published
7597 $ref: '#/components/schemas/VideoScheduledUpdate'
7599 description: Video thumbnail file
7603 description: Video preview file
7609 VideoUploadRequestLegacy:
7611 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7617 description: Video file
7620 VideoUploadRequestResumable:
7622 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7628 description: Video filename including extension
7631 example: what_is_peertube.mp4
7633 description: Video thumbnail file
7637 description: Video preview file
7640 VideoUploadResponse:
7646 $ref: '#/components/schemas/Video/properties/id'
7648 $ref: '#/components/schemas/Video/properties/uuid'
7650 $ref: '#/components/schemas/Video/properties/shortUUID'
7651 CommentThreadResponse:
7660 $ref: '#/components/schemas/VideoComment'
7661 CommentThreadPostResponse:
7664 $ref: '#/components/schemas/VideoComment'
7684 $ref: '#/components/schemas/Video'
7688 $ref: '#/components/schemas/Account'
7691 description: Automatically start playing the upcoming video after the currently playing video
7692 autoPlayNextVideoPlaylist:
7694 description: Automatically start playing the video on the playlist after the currently playing video
7697 description: Automatically start playing the video on the watch page
7707 description: The user email
7710 description: Has the user confirmed their email address?
7713 - $ref: '#/components/schemas/id'
7717 description: Auth plugin to use to authenticate the user
7721 noInstanceConfigWarningModal:
7723 noAccountSetupWarningModal:
7728 $ref: '#/components/schemas/NSFWPolicy'
7733 $ref: '#/components/schemas/UserRole'
7742 description: Theme enabled by this user
7744 $ref: '#/components/schemas/username'
7748 $ref: '#/components/schemas/VideoChannel'
7751 description: The user video quota in bytes
7755 description: The user daily video quota in bytes
7759 description: Enable P2P in the player
7762 - $ref: '#/components/schemas/User'
7764 # optionally present fields: they require WITH_STATS scope
7767 description: Count of videos published
7770 description: Count of reports/abuses of which the user is a target
7771 abusesAcceptedCount:
7773 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
7776 description: Count of reports/abuses created by the user
7779 description: Count of comments published
7783 $ref: '#/components/schemas/username'
7785 $ref: '#/components/schemas/password'
7789 description: The user email
7792 description: The user video quota in bytes
7796 description: The user daily video quota in bytes
7799 $ref: '#/components/schemas/usernameChannel'
7801 $ref: '#/components/schemas/UserRole'
7803 $ref: '#/components/schemas/UserAdminFlags'
7814 description: The updated email of the user
7816 - $ref: '#/components/schemas/User/properties/email'
7819 description: Set the email as verified
7822 description: The updated video quota of the user in bytes
7825 description: The updated daily video quota of the user in bytes
7829 description: The auth plugin to use to authenticate the user
7830 example: 'peertube-plugin-auth-saml2'
7832 $ref: '#/components/schemas/UserRole'
7834 $ref: '#/components/schemas/UserAdminFlags'
7836 $ref: '#/components/schemas/password'
7838 # see shared/models/users/user-update-me.model.ts:
7841 $ref: '#/components/schemas/password'
7843 $ref: '#/components/schemas/password'
7845 description: new email used for login and service communications
7847 - $ref: '#/components/schemas/User/properties/email'
7850 description: new name of the user in its representations
7855 description: new NSFW display policy
7862 description: whether to enable P2P in the player or not
7865 description: new preference regarding playing videos automatically
7868 description: new preference regarding playing following videos automatically
7869 autoPlayNextVideoPlaylist:
7871 description: new preference regarding playing following playlist videos automatically
7872 videosHistoryEnabled:
7874 description: whether to keep track of watched history or not
7879 description: list of languages to filter videos down to
7882 noInstanceConfigWarningModal:
7884 noAccountSetupWarningModal:
7891 $ref: '#/components/schemas/id'
7898 description: Rating of the video
7905 $ref: '#/components/schemas/Video'
7912 description: Rating of the video
7920 description: immutable name of the user, used to find or mention its actor
7922 - $ref: '#/components/schemas/username'
7924 $ref: '#/components/schemas/password'
7928 description: email of the user, used for login or service communications
7931 description: editable name of the user, displayed in its representations
7936 description: channel base information used to create the first channel of the user
7939 $ref: '#/components/schemas/usernameChannel'
7947 UserRegistrationRequest:
7949 - $ref: '#/components/schemas/RegisterUser'
7954 description: reason for the user to register on the instance
7956 - registrationReason
7958 UserRegistrationAcceptOrReject:
7963 description: Moderation response to send to the user
7965 - moderationResponse
7970 $ref: '#/components/schemas/id'
7980 description: 'The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
8010 description: If the registration has been accepted, this is a partial user object created by the registration
8013 $ref: '#/components/schemas/id'
8019 pattern: /^[a-z0-9]$/
8022 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
8025 pattern: /^[a-zA-Z0-9]$/
8028 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
8029 OAuthToken-password:
8031 - $ref: '#/components/schemas/OAuthClient'
8041 $ref: '#/components/schemas/User/properties/username'
8043 $ref: '#/components/schemas/password'
8050 OAuthToken-refresh_token:
8052 - $ref: '#/components/schemas/OAuthClient'
8063 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
8072 - $ref: '#/components/schemas/Actor'
8077 description: editable name of the channel, displayed in its representations
8078 example: Videos of Framasoft
8083 example: Videos made with <3 by Framasoft
8088 description: text shown by default on all videos of this channel, to tell the audience how to support it
8089 example: Please support our work on https://soutenir.framasoft.org/en/ <3
8102 $ref: '#/components/schemas/ActorImage'
8111 $ref: '#/components/schemas/UUIDv4'
8115 - $ref: '#/components/schemas/VideoChannel'
8118 description: username of the channel to create
8120 - $ref: '#/components/schemas/usernameChannel'
8126 - $ref: '#/components/schemas/VideoChannel'
8128 bulkVideosSupportUpdate:
8130 description: Update the support field for all videos of this channel
8140 - $ref: '#/components/schemas/VideoChannel'
8141 - $ref: '#/components/schemas/Actor'
8143 ImportVideosInChannelCreate:
8148 example: https://youtube.com/c/UC_myfancychannel
8151 description: If part of a channel sync process, specify its id to assign video imports to this channel synchronization
8153 - 'externalChannelUrl'
8159 $ref: '#/components/schemas/id'
8171 example: 'https://youtube.com/c/UC_myfancychannel'
8180 $ref: '#/components/schemas/VideoChannel'
8181 VideoChannelSyncList:
8191 - $ref: '#/components/schemas/VideoChannelSync'
8192 VideoChannelSyncCreate:
8197 example: https://youtube.com/c/UC_myfancychannel
8199 $ref: '#/components/schemas/id'
8203 name: 'media:peerLink'
8212 - application/x-bittorrent
8218 name: 'media:content'
8249 VideoCommentsForXML:
8284 description: video watch page URL
8287 description: video canonical URL
8291 description: video publication date
8294 description: video description
8297 description: video description
8300 description: publisher user name
8303 description: video category (MRSS)
8306 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
8321 description: video embed path, relative to the canonical URL domain (MRSS)
8330 description: video watch path, relative to the canonical URL domain (MRSS)
8351 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
8352 'media:description':
8359 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
8362 description: main streamable file for the video
8372 - application/x-bittorrent
8381 description: list of streamable files for the video. see [media:peerLink](https://www.rssboard.org/media-rss#media-peerlink) and [media:content](https://www.rssboard.org/media-rss#media-content) or (MRSS)
8384 - $ref: '#/components/schemas/MRSSPeerLink'
8385 - $ref: '#/components/schemas/MRSSGroupContent'
8386 NotificationSettingValue:
8389 Notification type. One of the following values, or a sum of multiple values:
8399 $ref: '#/components/schemas/id'
8403 Notification type, following the `UserNotificationType` enum:
8405 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
8407 - `2` NEW_COMMENT_ON_MY_VIDEO
8409 - `3` NEW_ABUSE_FOR_MODERATORS
8411 - `4` BLACKLIST_ON_MY_VIDEO
8413 - `5` UNBLACKLIST_ON_MY_VIDEO
8415 - `6` MY_VIDEO_PUBLISHED
8417 - `7` MY_VIDEO_IMPORT_SUCCESS
8419 - `8` MY_VIDEO_IMPORT_ERROR
8421 - `9` NEW_USER_REGISTRATION
8425 - `11` COMMENT_MENTION
8427 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
8429 - `13` NEW_INSTANCE_FOLLOWER
8431 - `14` AUTO_INSTANCE_FOLLOWING
8433 - `15` ABUSE_STATE_CHANGE
8435 - `16` ABUSE_NEW_MESSAGE
8437 - `17` NEW_PLUGIN_VERSION
8439 - `18` NEW_PEERTUBE_VERSION
8445 - $ref: '#/components/schemas/VideoInfo'
8449 $ref: '#/components/schemas/ActorInfo'
8455 $ref: '#/components/schemas/id'
8458 $ref: '#/components/schemas/VideoInfo'
8463 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
8473 $ref: '#/components/schemas/id'
8477 $ref: '#/components/schemas/VideoInfo'
8479 $ref: '#/components/schemas/ActorInfo'
8485 $ref: '#/components/schemas/id'
8488 - $ref: '#/components/schemas/VideoInfo'
8494 $ref: '#/components/schemas/id'
8497 - $ref: '#/components/schemas/VideoInfo'
8501 - $ref: '#/components/schemas/ActorInfo'
8507 $ref: '#/components/schemas/id'
8509 $ref: '#/components/schemas/ActorInfo'
8537 NotificationListResponse:
8546 $ref: '#/components/schemas/Notification'
8551 example: peertube-plugin-auth-ldap
8579 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
8582 additionalProperties: true
8598 $ref: '#/components/schemas/Plugin'
8605 description: User can stream multiple times in a permanent live
8608 description: User can select live latency mode if enabled by the instance
8609 $ref: '#/components/schemas/LiveVideoLatencyMode'
8615 description: Included in the response if an appropriate token is provided
8618 description: Included in the response if an appropriate token is provided
8621 description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
8625 description: User can stream multiple times in a permanent live
8628 description: User can select live latency mode if enabled by the instance
8629 $ref: '#/components/schemas/LiveVideoLatencyMode'
8631 RequestTwoFactorResponse:
8638 description: The token to send to confirm this request
8641 description: The OTP secret
8644 description: The OTP URI
8646 VideoStudioCreateTask:
8694 title: add-watermark
8708 LiveVideoSessionResponse:
8715 description: Start date of the live session
8720 description: End date of the live session
8731 Error type if an error occurred during the live session:
8732 - `1`: Bad socket health (transcoding is too slow)
8733 - `2`: Max duration exceeded
8734 - `3`: Quota exceeded
8735 - `4`: Quota FFmpeg error
8736 - `5`: Video has been blacklisted during the live
8739 description: Video replay information
8744 $ref: '#/components/schemas/UUIDv4'
8746 $ref: '#/components/schemas/shortUUID'
8748 PlaybackMetricCreate:
8753 - 'p2p-media-loader'
8757 description: Current player video resolution
8760 description: Current player video fps
8763 description: How many resolution changes occured since the last metric creation
8766 description: How many errors occured since the last metric creation
8769 description: How many bytes were downloaded with P2P since the last metric creation
8770 downloadedBytesHTTP:
8772 description: How many bytes were downloaded with HTTP since the last metric creation
8775 description: How many bytes were uploaded with P2P since the last metric creation
8778 - $ref: '#/components/schemas/id'
8779 - $ref: '#/components/schemas/UUIDv4'
8780 - $ref: '#/components/schemas/shortUUID'
8785 - downloadedBytesP2P
8786 - downloadedBytesHTTP
8792 'https://search.example.org/api/v1/search/videos':
8794 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
8797 description: successful operation
8801 $ref: '#/components/schemas/VideoListResponse'