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/register:
1406 summary: Register a user
1407 operationId: registerUser
1413 description: successful operation
1418 $ref: '#/components/schemas/RegisterUser'
1421 /api/v1/users/{id}/verify-email:
1423 summary: Verify a user
1424 operationId: verifyUser
1426 Following a user registration, the new user will receive an email asking to click a link
1427 containing a secret.
1432 - $ref: '#/components/parameters/id'
1445 - verificationString
1448 description: successful operation
1450 description: invalid verification string
1452 description: user not found
1454 /api/v1/users/{id}/two-factor/request:
1456 summary: Request two factor auth
1457 operationId: requestTwoFactor
1458 description: Request two factor authentication for a user
1462 - $ref: '#/components/parameters/id'
1471 description: Password of the currently authenticated user
1474 description: successful operation
1480 $ref: '#/components/schemas/RequestTwoFactorResponse'
1482 description: invalid password
1484 description: user not found
1486 /api/v1/users/{id}/two-factor/confirm-request:
1488 summary: Confirm two factor auth
1489 operationId: confirmTwoFactorRequest
1490 description: Confirm a two factor authentication request
1494 - $ref: '#/components/parameters/id'
1503 description: Token to identify the two factor request
1506 description: OTP token generated by the app
1512 description: successful operation
1514 description: invalid request token or OTP token
1516 description: user not found
1518 /api/v1/users/{id}/two-factor/disable:
1520 summary: Disable two factor auth
1521 operationId: disableTwoFactor
1522 description: Disable two factor authentication of a user
1526 - $ref: '#/components/parameters/id'
1535 description: Password of the currently authenticated user
1538 description: successful operation
1540 description: invalid password
1542 description: user not found
1545 /api/v1/users/ask-send-verify-email:
1547 summary: Resend user verification link
1548 operationId: resendEmailToVerifyUser
1554 description: successful operation
1558 summary: Get my user information
1559 operationId: getUserInfo
1567 description: successful operation
1573 $ref: '#/components/schemas/User'
1575 summary: Update my user information
1576 operationId: putUserInfo
1584 description: successful operation
1589 $ref: '#/components/schemas/UpdateMe'
1592 /api/v1/users/me/videos/imports:
1594 summary: Get video imports of my user
1602 - $ref: '#/components/parameters/start'
1603 - $ref: '#/components/parameters/count'
1604 - $ref: '#/components/parameters/sort'
1609 description: Filter on import target URL
1613 name: videoChannelSyncId
1616 description: Filter on imports created by a specific channel synchronization
1623 description: Search in video names
1628 description: successful operation
1632 $ref: '#/components/schemas/VideoImportsList'
1634 /api/v1/users/me/video-quota-used:
1636 summary: Get my user used quota
1644 description: successful operation
1652 description: The user video quota used so far in bytes
1653 example: 16810141515
1654 videoQuotaUsedDaily:
1656 description: The user video quota used today in bytes
1659 '/api/v1/users/me/videos/{videoId}/rating':
1661 summary: Get rate of my user for a video
1671 description: The video id
1673 $ref: '#/components/schemas/Video/properties/id'
1676 description: successful operation
1680 $ref: '#/components/schemas/GetMeVideoRating'
1682 /api/v1/users/me/videos:
1684 summary: Get videos of my user
1692 - $ref: '#/components/parameters/start'
1693 - $ref: '#/components/parameters/count'
1694 - $ref: '#/components/parameters/sort'
1697 description: successful operation
1701 $ref: '#/components/schemas/VideoListResponse'
1703 /api/v1/users/me/subscriptions:
1705 summary: Get my user subscriptions
1712 - $ref: '#/components/parameters/start'
1713 - $ref: '#/components/parameters/count'
1714 - $ref: '#/components/parameters/sort'
1717 description: successful operation
1721 $ref: '#/components/schemas/VideoChannelList'
1725 summary: Add subscription to my user
1738 description: uri of the video channels to subscribe to
1744 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1747 description: successful operation
1749 /api/v1/users/me/subscriptions/exist:
1751 summary: Get if subscriptions exist for my user
1758 - $ref: '#/components/parameters/subscriptionsUris'
1761 description: successful operation
1767 /api/v1/users/me/subscriptions/videos:
1769 summary: List videos of subscriptions of my user
1777 - $ref: '#/components/parameters/categoryOneOf'
1778 - $ref: '#/components/parameters/isLive'
1779 - $ref: '#/components/parameters/tagsOneOf'
1780 - $ref: '#/components/parameters/tagsAllOf'
1781 - $ref: '#/components/parameters/licenceOneOf'
1782 - $ref: '#/components/parameters/languageOneOf'
1783 - $ref: '#/components/parameters/nsfw'
1784 - $ref: '#/components/parameters/isLocal'
1785 - $ref: '#/components/parameters/include'
1786 - $ref: '#/components/parameters/privacyOneOf'
1787 - $ref: '#/components/parameters/hasHLSFiles'
1788 - $ref: '#/components/parameters/hasWebtorrentFiles'
1789 - $ref: '#/components/parameters/skipCount'
1790 - $ref: '#/components/parameters/start'
1791 - $ref: '#/components/parameters/count'
1792 - $ref: '#/components/parameters/videosSort'
1795 description: successful operation
1799 $ref: '#/components/schemas/VideoListResponse'
1801 '/api/v1/users/me/subscriptions/{subscriptionHandle}':
1803 summary: Get subscription of my user
1810 - $ref: '#/components/parameters/subscriptionHandle'
1813 description: successful operation
1817 $ref: '#/components/schemas/VideoChannel'
1819 summary: Delete subscription of my user
1826 - $ref: '#/components/parameters/subscriptionHandle'
1829 description: successful operation
1831 /api/v1/users/me/notifications:
1833 summary: List my notifications
1841 description: only list unread notifications
1844 - $ref: '#/components/parameters/start'
1845 - $ref: '#/components/parameters/count'
1846 - $ref: '#/components/parameters/sort'
1849 description: successful operation
1853 $ref: '#/components/schemas/NotificationListResponse'
1855 /api/v1/users/me/notifications/read:
1857 summary: Mark notifications as read by their id
1870 description: ids of the notifications to mark as read
1877 description: successful operation
1879 /api/v1/users/me/notifications/read-all:
1881 summary: Mark all my notification as read
1888 description: successful operation
1890 /api/v1/users/me/notification-settings:
1892 summary: Update my notification settings
1903 newVideoFromSubscription:
1904 $ref: '#/components/schemas/NotificationSettingValue'
1905 newCommentOnMyVideo:
1906 $ref: '#/components/schemas/NotificationSettingValue'
1908 $ref: '#/components/schemas/NotificationSettingValue'
1909 videoAutoBlacklistAsModerator:
1910 $ref: '#/components/schemas/NotificationSettingValue'
1912 $ref: '#/components/schemas/NotificationSettingValue'
1914 $ref: '#/components/schemas/NotificationSettingValue'
1915 myVideoImportFinished:
1916 $ref: '#/components/schemas/NotificationSettingValue'
1918 $ref: '#/components/schemas/NotificationSettingValue'
1919 newUserRegistration:
1920 $ref: '#/components/schemas/NotificationSettingValue'
1922 $ref: '#/components/schemas/NotificationSettingValue'
1923 newInstanceFollower:
1924 $ref: '#/components/schemas/NotificationSettingValue'
1925 autoInstanceFollowing:
1926 $ref: '#/components/schemas/NotificationSettingValue'
1929 description: successful operation
1931 /api/v1/users/me/history/videos:
1933 summary: List watched videos history
1939 - $ref: '#/components/parameters/start'
1940 - $ref: '#/components/parameters/count'
1941 - $ref: '#/components/parameters/search'
1944 description: successful operation
1948 $ref: '#/components/schemas/VideoListResponse'
1950 /api/v1/users/me/history/videos/{videoId}:
1952 summary: Delete history element
1962 $ref: '#/components/schemas/Video/properties/id'
1965 description: successful operation
1967 /api/v1/users/me/history/videos/remove:
1969 summary: Clear video history
1976 multipart/form-data:
1981 description: history before this date will be deleted
1986 description: successful operation
1988 /api/v1/users/me/avatar/pick:
1990 summary: Update my user avatar
1997 description: successful operation
2006 $ref: '#/components/schemas/ActorImage'
2008 description: image file too large
2010 X-File-Maximum-Size:
2014 description: Maximum file size for the avatar
2017 multipart/form-data:
2022 description: The file to upload
2027 contentType: image/png, image/jpeg
2029 /api/v1/users/me/avatar:
2031 summary: Delete my avatar
2038 description: successful operation
2040 /api/v1/videos/ownership:
2042 summary: List video ownership changes
2044 - Video Ownership Change
2049 description: successful operation
2051 '/api/v1/videos/ownership/{id}/accept':
2053 summary: Accept ownership change request
2055 - Video Ownership Change
2059 - $ref: '#/components/parameters/idOrUUID'
2062 description: successful operation
2064 description: cannot terminate an ownership change of another user
2066 description: video ownership change not found
2068 '/api/v1/videos/ownership/{id}/refuse':
2070 summary: Refuse ownership change request
2072 - Video Ownership Change
2076 - $ref: '#/components/parameters/idOrUUID'
2079 description: successful operation
2081 description: cannot terminate an ownership change of another user
2083 description: video ownership change not found
2085 '/api/v1/videos/{id}/give-ownership':
2087 summary: Request ownership change
2089 - Video Ownership Change
2093 - $ref: '#/components/parameters/idOrUUID'
2097 application/x-www-form-urlencoded:
2107 description: successful operation
2109 description: changing video ownership to a remote account is not supported yet
2111 description: video not found
2113 '/api/v1/videos/{id}/token':
2115 summary: Request video token
2116 operationId: requestVideoToken
2117 description: Request special tokens that expire quickly to use them in some context (like accessing private static files)
2123 - $ref: '#/components/parameters/idOrUUID'
2126 description: successful operation
2130 $ref: '#/components/schemas/VideoTokenResponse'
2132 description: incorrect parameters
2134 description: video not found
2136 /api/v1/videos/{id}/studio/edit:
2138 summary: Create a studio task
2142 description: Create a task to edit a video (cut, add intro/outro etc)
2146 - $ref: '#/components/parameters/idOrUUID'
2150 application/x-www-form-urlencoded:
2152 $ref: '#/components/schemas/VideoStudioCreateTask'
2155 description: successful operation
2157 description: incorrect parameters
2159 description: video not found
2163 summary: List videos
2164 operationId: getVideos
2168 - $ref: '#/components/parameters/categoryOneOf'
2169 - $ref: '#/components/parameters/isLive'
2170 - $ref: '#/components/parameters/tagsOneOf'
2171 - $ref: '#/components/parameters/tagsAllOf'
2172 - $ref: '#/components/parameters/licenceOneOf'
2173 - $ref: '#/components/parameters/languageOneOf'
2174 - $ref: '#/components/parameters/nsfw'
2175 - $ref: '#/components/parameters/isLocal'
2176 - $ref: '#/components/parameters/include'
2177 - $ref: '#/components/parameters/privacyOneOf'
2178 - $ref: '#/components/parameters/hasHLSFiles'
2179 - $ref: '#/components/parameters/hasWebtorrentFiles'
2180 - $ref: '#/components/parameters/skipCount'
2181 - $ref: '#/components/parameters/start'
2182 - $ref: '#/components/parameters/count'
2183 - $ref: '#/components/parameters/videosSort'
2186 description: successful operation
2190 $ref: '#/components/schemas/VideoListResponse'
2192 /api/v1/videos/categories:
2194 summary: List available video categories
2195 operationId: getCategories
2200 description: successful operation
2209 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
2211 /api/v1/videos/licences:
2213 summary: List available video licences
2214 operationId: getLicences
2219 description: successful operation
2228 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
2230 /api/v1/videos/languages:
2232 summary: List available video languages
2233 operationId: getLanguages
2238 description: successful operation
2247 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
2249 /api/v1/videos/privacies:
2251 summary: List available video privacy policies
2252 operationId: getPrivacyPolicies
2257 description: successful operation
2266 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
2268 '/api/v1/videos/{id}':
2270 summary: Update a video
2271 operationId: putVideo
2277 - $ref: '#/components/parameters/idOrUUID'
2280 description: successful operation
2283 multipart/form-data:
2288 description: Video thumbnail file
2292 description: Video preview file
2296 $ref: '#/components/schemas/VideoCategorySet'
2298 $ref: '#/components/schemas/VideoLicenceSet'
2300 $ref: '#/components/schemas/VideoLanguageSet'
2302 $ref: '#/components/schemas/VideoPrivacySet'
2304 description: Video description
2307 description: Whether or not we wait transcoding before publish the video
2310 description: A text tell the audience how to support the video creator
2311 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2314 description: Whether or not this video contains sensitive content
2317 description: Video name
2322 description: Video tags (maximum 5 tags each between 2 and 30 characters)
2331 description: Enable or disable comments for this video
2334 description: Enable or disable downloading for this video
2336 originallyPublishedAt:
2337 description: Date when the content was originally published
2341 $ref: '#/components/schemas/VideoScheduledUpdate'
2344 contentType: image/jpeg
2346 contentType: image/jpeg
2348 summary: Get a video
2349 operationId: getVideo
2353 - $ref: '#/components/parameters/idOrUUID'
2356 description: successful operation
2360 $ref: '#/components/schemas/VideoDetails'
2362 summary: Delete a video
2363 operationId: delVideo
2369 - $ref: '#/components/parameters/idOrUUID'
2372 description: successful operation
2374 '/api/v1/videos/{id}/description':
2376 summary: Get complete video description
2377 operationId: getVideoDesc
2381 - $ref: '#/components/parameters/idOrUUID'
2384 description: successful operation
2393 **[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)**
2395 '/api/v1/videos/{id}/source':
2397 summary: Get video source file metadata
2398 operationId: getVideoSource
2402 - $ref: '#/components/parameters/idOrUUID'
2405 description: successful operation
2409 $ref: '#/components/schemas/VideoSource'
2411 '/api/v1/videos/{id}/views':
2413 summary: Notify user is watching a video
2414 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.
2415 operationId: addView
2419 - $ref: '#/components/parameters/idOrUUID'
2424 $ref: '#/components/schemas/UserViewingVideo'
2428 description: successful operation
2430 '/api/v1/videos/{id}/watching':
2432 summary: Set watching progress of a video
2434 description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
2440 - $ref: '#/components/parameters/idOrUUID'
2445 $ref: '#/components/schemas/UserViewingVideo'
2449 description: successful operation
2451 '/api/v1/videos/{id}/stats/overall':
2453 summary: Get overall stats of a video
2459 - $ref: '#/components/parameters/idOrUUID'
2462 description: Filter stats by start date
2468 description: Filter stats by end date
2474 description: successful operation
2478 $ref: '#/components/schemas/VideoStatsOverall'
2480 '/api/v1/videos/{id}/stats/retention':
2482 summary: Get retention stats of a video
2488 - $ref: '#/components/parameters/idOrUUID'
2491 description: successful operation
2495 $ref: '#/components/schemas/VideoStatsRetention'
2497 '/api/v1/videos/{id}/stats/timeseries/{metric}':
2499 summary: Get timeserie stats of a video
2505 - $ref: '#/components/parameters/idOrUUID'
2510 description: The metric to get
2515 - 'aggregateWatchTime'
2518 description: Filter stats by start date
2524 description: Filter stats by end date
2530 description: successful operation
2534 $ref: '#/components/schemas/VideoStatsTimeserie'
2536 /api/v1/videos/upload:
2538 summary: Upload a video
2539 description: Uses a single request to upload a video.
2540 operationId: uploadLegacy
2548 description: successful operation
2552 $ref: '#/components/schemas/VideoUploadResponse'
2554 description: video didn't pass upload filter
2556 description: upload has timed out
2558 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
2560 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
2561 - `quota_reached` for quota limits whether daily or global
2563 X-File-Maximum-Size:
2567 description: Maximum file size for the video
2569 description: video type unsupported
2571 description: video unreadable
2574 multipart/form-data:
2576 $ref: '#/components/schemas/VideoUploadRequestLegacy'
2579 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
2581 contentType: image/jpeg
2583 contentType: image/jpeg
2588 USERNAME="<your_username>"
2589 PASSWORD="<your_password>"
2590 FILE_PATH="<your_file_path>"
2591 CHANNEL_ID="<your_channel_id>"
2593 API="https://peertube2.cpy.re/api/v1"
2596 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
2597 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
2598 token=$(curl -s "$API/users/token" \
2599 --data client_id="$client_id" \
2600 --data client_secret="$client_secret" \
2601 --data grant_type=password \
2602 --data username="$USERNAME" \
2603 --data password="$PASSWORD" \
2604 | jq -r ".access_token")
2607 curl -s "$API/videos/upload" \
2608 -H "Authorization: Bearer $token" \
2610 --form videofile=@"$FILE_PATH" \
2611 --form channelId=$CHANNEL_ID \
2614 /api/v1/videos/upload-resumable:
2616 summary: Initialize the resumable upload of a video
2617 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
2618 operationId: uploadResumableInit
2625 - name: X-Upload-Content-Length
2631 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2632 - name: X-Upload-Content-Type
2639 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2644 $ref: '#/components/schemas/VideoUploadRequestResumable'
2647 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2649 description: created
2655 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2661 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2663 Disambiguate via `type`:
2664 - `max_file_size_reached` for the absolute file size limit
2665 - `quota_reached` for quota limits whether daily or global
2667 description: video type unsupported
2669 summary: Send chunk for the resumable upload of a video
2670 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
2671 operationId: uploadResumable
2682 Created session id to proceed with. If you didn't send chunks in the last hour, it is
2683 not valid anymore and you need to initialize a new upload.
2686 - name: Content-Range
2690 example: bytes 0-262143/2469036
2693 Specifies the bytes in the file that the request is uploading.
2695 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2696 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2697 - name: Content-Length
2704 Size of the chunk that the request is sending.
2706 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2707 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2710 application/octet-stream:
2716 description: last chunk received
2724 $ref: '#/components/schemas/VideoUploadResponse'
2726 description: resume incomplete
2731 example: bytes=0-262143
2737 description: video didn't pass upload filter
2739 description: upload not found
2741 description: chunk doesn't match range
2743 description: video unreadable
2745 description: too many concurrent requests
2747 description: upload is already being processed
2754 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2755 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2756 operationId: uploadResumableCancel
2767 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2768 not valid anymore and the upload session has already been deleted with its data ;-)
2771 - name: Content-Length
2779 description: upload cancelled
2786 description: upload not found
2788 /api/v1/videos/imports:
2790 summary: Import a video
2791 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2792 operationId: importVideo
2800 multipart/form-data:
2802 $ref: '#/components/schemas/VideoCreateImport'
2805 contentType: application/x-bittorrent
2807 contentType: image/jpeg
2809 contentType: image/jpeg
2812 description: successful operation
2816 $ref: '#/components/schemas/VideoUploadResponse'
2818 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2820 description: video didn't pass pre-import filter
2822 description: HTTP or Torrent/magnetURI import not enabled
2824 /api/v1/videos/imports/{id}/cancel:
2826 summary: Cancel video import
2827 description: Cancel a pending video import
2833 - $ref: '#/components/parameters/id'
2836 description: successful operation
2838 /api/v1/videos/imports/{id}:
2840 summary: Delete video import
2841 description: Delete ended video import
2847 - $ref: '#/components/parameters/id'
2850 description: successful operation
2852 /api/v1/videos/live:
2854 summary: Create a live
2855 operationId: addLive
2863 description: successful operation
2867 $ref: '#/components/schemas/VideoUploadResponse'
2869 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2871 Disambiguate via `type`:
2872 - default type for a validation error
2873 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2875 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2877 Disambiguate via `type`:
2878 - `live_not_enabled` for a disabled live feature
2879 - `live_not_allowing_replay` for a disabled replay feature
2880 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2881 - `max_user_lives_limit_reached` for the user concurrent live limit
2884 multipart/form-data:
2889 description: Channel id that will contain this live video
2894 description: User can stream multiple times in a permanent live
2897 description: User can select live latency mode if enabled by the instance
2898 $ref: '#/components/schemas/LiveVideoLatencyMode'
2900 description: Live video/replay thumbnail file
2904 description: Live video/replay preview file
2908 $ref: '#/components/schemas/VideoPrivacySet'
2910 $ref: '#/components/schemas/VideoCategorySet'
2912 $ref: '#/components/schemas/VideoLicenceSet'
2914 $ref: '#/components/schemas/VideoLanguageSet'
2916 description: Live video/replay description
2919 description: A text tell the audience how to support the creator
2920 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2923 description: Whether or not this live video/replay contains sensitive content
2926 description: Live video/replay name
2931 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2940 description: Enable or disable comments for this live video/replay
2943 description: Enable or disable downloading for the replay of this live video
2950 contentType: image/jpeg
2952 contentType: image/jpeg
2954 /api/v1/videos/live/{id}:
2956 summary: Get information about a live
2957 operationId: getLiveId
2964 - $ref: '#/components/parameters/idOrUUID'
2967 description: successful operation
2971 $ref: '#/components/schemas/LiveVideoResponse'
2973 summary: Update information about a live
2974 operationId: updateLiveId
2981 - $ref: '#/components/parameters/idOrUUID'
2986 $ref: '#/components/schemas/LiveVideoUpdate'
2989 description: successful operation
2991 description: bad parameters or trying to update a live that has already started
2993 description: trying to save replay of the live but saving replay is not enabled on the instance
2994 /api/v1/videos/live/{id}/sessions:
2996 summary: List live sessions
2997 description: List all sessions created in a particular live
3003 - $ref: '#/components/parameters/idOrUUID'
3006 description: successful operation
3018 $ref: '#/components/schemas/LiveVideoSessionResponse'
3019 /api/v1/videos/{id}/live-session:
3021 summary: Get live session of a replay
3022 description: If the video is a replay of a live, you can find the associated live session using this endpoint
3028 - $ref: '#/components/parameters/idOrUUID'
3031 description: successful operation
3035 $ref: '#/components/schemas/LiveVideoSessionResponse'
3037 /api/v1/users/me/abuses:
3039 summary: List my abuses
3040 operationId: getMyAbuses
3049 description: only list the report with this id
3055 $ref: '#/components/schemas/AbuseStateSet'
3056 - $ref: '#/components/parameters/abusesSort'
3057 - $ref: '#/components/parameters/start'
3058 - $ref: '#/components/parameters/count'
3061 description: successful operation
3073 $ref: '#/components/schemas/Abuse'
3077 summary: List abuses
3078 operationId: getAbuses
3088 description: only list the report with this id
3091 - name: predefinedReason
3093 description: predefined reason the listed reports should contain
3095 $ref: '#/components/schemas/PredefinedAbuseReasons'
3098 description: plain search that will match with video titles, reporter names and more
3104 $ref: '#/components/schemas/AbuseStateSet'
3105 - name: searchReporter
3107 description: only list reports of a specific reporter
3110 - name: searchReportee
3111 description: only list reports of a specific reportee
3117 description: only list reports of a specific video
3120 - name: searchVideoChannel
3122 description: only list reports of a specific video channel
3127 description: only list deleted or blocklisted videos
3135 description: only list account, comment or video reports
3142 - $ref: '#/components/parameters/start'
3143 - $ref: '#/components/parameters/count'
3144 - $ref: '#/components/parameters/abusesSort'
3147 description: successful operation
3159 $ref: '#/components/schemas/Abuse'
3161 summary: Report an abuse
3174 description: Reason why the user reports this video
3179 $ref: '#/components/schemas/PredefinedAbuseReasons'
3184 description: Video id to report
3186 - $ref: '#/components/schemas/Video/properties/id'
3190 description: Timestamp in the video that marks the beginning of the report
3195 description: Timestamp in the video that marks the ending of the report
3201 description: Comment id to report
3203 - $ref: '#/components/schemas/VideoComment/properties/id'
3208 description: Account id to report
3214 description: successful operation
3224 $ref: '#/components/schemas/id'
3226 description: incorrect request parameters
3228 '/api/v1/abuses/{abuseId}':
3230 summary: Update an abuse
3238 - $ref: '#/components/parameters/abuseId'
3246 $ref: '#/components/schemas/AbuseStateSet'
3249 description: Update the report comment visible only to the moderation team
3254 description: successful operation
3256 description: abuse not found
3260 summary: Delete an abuse
3266 - $ref: '#/components/parameters/abuseId'
3269 description: successful operation
3271 description: block not found
3273 '/api/v1/abuses/{abuseId}/messages':
3275 summary: List messages of an abuse
3281 - $ref: '#/components/parameters/abuseId'
3284 description: successful operation
3296 $ref: '#/components/schemas/AbuseMessage'
3298 summary: Add message to an abuse
3304 - $ref: '#/components/parameters/abuseId'
3313 description: Message to send
3321 description: successful operation
3323 description: incorrect request parameters
3325 '/api/v1/abuses/{abuseId}/messages/{abuseMessageId}':
3327 summary: Delete an abuse message
3333 - $ref: '#/components/parameters/abuseId'
3334 - $ref: '#/components/parameters/abuseMessageId'
3337 description: successful operation
3339 '/api/v1/videos/{id}/blacklist':
3341 summary: Block a video
3342 operationId: addVideoBlock
3350 - $ref: '#/components/parameters/idOrUUID'
3353 description: successful operation
3355 summary: Unblock a video by its id
3356 operationId: delVideoBlock
3364 - $ref: '#/components/parameters/idOrUUID'
3367 description: successful operation
3369 description: block not found
3371 /api/v1/videos/blacklist:
3375 summary: List video blocks
3376 operationId: getVideoBlocks
3385 list only blocks that match this type:
3389 - `2`: automatic block that needs review
3397 description: plain search that will match with video titles, and more
3400 - $ref: '#/components/parameters/start'
3401 - $ref: '#/components/parameters/count'
3402 - $ref: '#/components/parameters/blacklistsSort'
3405 description: successful operation
3417 $ref: '#/components/schemas/VideoBlacklist'
3419 /api/v1/videos/{id}/captions:
3421 summary: List captions of a video
3422 operationId: getVideoCaptions
3426 - $ref: '#/components/parameters/idOrUUID'
3429 description: successful operation
3441 $ref: '#/components/schemas/VideoCaption'
3443 /api/v1/videos/{id}/captions/{captionLanguage}:
3445 summary: Add or replace a video caption
3446 operationId: addVideoCaption
3453 - $ref: '#/components/parameters/idOrUUID'
3454 - $ref: '#/components/parameters/captionLanguage'
3457 multipart/form-data:
3462 description: The file to upload.
3467 contentType: text/vtt, application/x-subrip, text/plain
3470 description: successful operation
3472 description: video or language not found
3474 summary: Delete a video caption
3475 operationId: delVideoCaption
3482 - $ref: '#/components/parameters/idOrUUID'
3483 - $ref: '#/components/parameters/captionLanguage'
3486 description: successful operation
3488 description: video or language or caption for that language not found
3490 /api/v1/video-channels:
3492 summary: List video channels
3493 operationId: getVideoChannels
3497 - $ref: '#/components/parameters/start'
3498 - $ref: '#/components/parameters/count'
3499 - $ref: '#/components/parameters/sort'
3502 description: successful operation
3506 $ref: '#/components/schemas/VideoChannelList'
3508 summary: Create a video channel
3509 operationId: addVideoChannel
3516 description: successful operation
3526 $ref: '#/components/schemas/id'
3531 $ref: '#/components/schemas/VideoChannelCreate'
3533 '/api/v1/video-channels/{channelHandle}':
3535 summary: Get a video channel
3536 operationId: getVideoChannel
3540 - $ref: '#/components/parameters/channelHandle'
3543 description: successful operation
3547 $ref: '#/components/schemas/VideoChannel'
3549 summary: Update a video channel
3550 operationId: putVideoChannel
3556 - $ref: '#/components/parameters/channelHandle'
3559 description: successful operation
3564 $ref: '#/components/schemas/VideoChannelUpdate'
3566 summary: Delete a video channel
3567 operationId: delVideoChannel
3573 - $ref: '#/components/parameters/channelHandle'
3576 description: successful operation
3578 '/api/v1/video-channels/{channelHandle}/videos':
3580 summary: List videos of a video channel
3581 operationId: getVideoChannelVideos
3586 - $ref: '#/components/parameters/channelHandle'
3587 - $ref: '#/components/parameters/categoryOneOf'
3588 - $ref: '#/components/parameters/isLive'
3589 - $ref: '#/components/parameters/tagsOneOf'
3590 - $ref: '#/components/parameters/tagsAllOf'
3591 - $ref: '#/components/parameters/licenceOneOf'
3592 - $ref: '#/components/parameters/languageOneOf'
3593 - $ref: '#/components/parameters/nsfw'
3594 - $ref: '#/components/parameters/isLocal'
3595 - $ref: '#/components/parameters/include'
3596 - $ref: '#/components/parameters/privacyOneOf'
3597 - $ref: '#/components/parameters/hasHLSFiles'
3598 - $ref: '#/components/parameters/hasWebtorrentFiles'
3599 - $ref: '#/components/parameters/skipCount'
3600 - $ref: '#/components/parameters/start'
3601 - $ref: '#/components/parameters/count'
3602 - $ref: '#/components/parameters/videosSort'
3605 description: successful operation
3609 $ref: '#/components/schemas/VideoListResponse'
3611 '/api/v1/video-channels/{channelHandle}/followers':
3615 summary: 'List followers of a video channel'
3618 operationId: getVideoChannelFollowers
3620 - $ref: '#/components/parameters/channelHandle'
3621 - $ref: '#/components/parameters/start'
3622 - $ref: '#/components/parameters/count'
3623 - $ref: '#/components/parameters/followersSort'
3624 - $ref: '#/components/parameters/search'
3627 description: successful operation
3639 $ref: '#/components/schemas/Follow'
3641 '/api/v1/video-channels/{channelHandle}/avatar/pick':
3643 summary: Update channel avatar
3649 - $ref: '#/components/parameters/channelHandle'
3652 description: successful operation
3661 $ref: '#/components/schemas/ActorImage'
3663 description: image file too large
3665 X-File-Maximum-Size:
3669 description: Maximum file size for the avatar
3672 multipart/form-data:
3677 description: The file to upload.
3682 contentType: image/png, image/jpeg
3684 '/api/v1/video-channels/{channelHandle}/avatar':
3686 summary: Delete channel avatar
3692 - $ref: '#/components/parameters/channelHandle'
3695 description: successful operation
3697 '/api/v1/video-channels/{channelHandle}/banner/pick':
3699 summary: Update channel banner
3705 - $ref: '#/components/parameters/channelHandle'
3708 description: successful operation
3717 $ref: '#/components/schemas/ActorImage'
3719 description: image file too large
3721 X-File-Maximum-Size:
3725 description: Maximum file size for the banner
3728 multipart/form-data:
3733 description: The file to upload.
3738 contentType: image/png, image/jpeg
3740 '/api/v1/video-channels/{channelHandle}/banner':
3742 summary: Delete channel banner
3748 - $ref: '#/components/parameters/channelHandle'
3751 description: successful operation
3753 '/api/v1/video-channels/{channelHandle}/import-videos':
3755 summary: Import videos in channel
3756 description: Import a remote channel/playlist videos into a channel
3763 - $ref: '#/components/parameters/channelHandle'
3768 $ref: '#/components/schemas/ImportVideosInChannelCreate'
3771 description: successful operation
3773 '/api/v1/video-channel-syncs':
3775 summary: Create a synchronization for a video channel
3776 operationId: addVideoChannelSync
3785 $ref: '#/components/schemas/VideoChannelSyncCreate'
3788 description: successful operation
3795 $ref: "#/components/schemas/VideoChannelSync"
3797 '/api/v1/video-channel-syncs/{channelSyncId}':
3799 summary: Delete a video channel synchronization
3800 operationId: delVideoChannelSync
3806 - $ref: '#/components/parameters/channelSyncId'
3809 description: successful operation
3811 '/api/v1/video-channel-syncs/{channelSyncId}/sync':
3813 summary: Triggers the channel synchronization job, fetching all the videos from the remote channel
3814 operationId: triggerVideoChannelSync
3820 - $ref: '#/components/parameters/channelSyncId'
3823 description: successful operation
3826 /api/v1/video-playlists/privacies:
3828 summary: List available playlist privacy policies
3829 operationId: getPlaylistPrivacyPolicies
3834 description: successful operation
3843 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3845 /api/v1/video-playlists:
3847 summary: List video playlists
3848 operationId: getPlaylists
3852 - $ref: '#/components/parameters/start'
3853 - $ref: '#/components/parameters/count'
3854 - $ref: '#/components/parameters/sort'
3857 description: successful operation
3869 $ref: '#/components/schemas/VideoPlaylist'
3871 summary: Create a video playlist
3872 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3873 operationId: addPlaylist
3880 description: successful operation
3890 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3892 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3894 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3897 multipart/form-data:
3902 description: Video playlist display name
3907 description: Video playlist thumbnail file
3911 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3913 description: Video playlist description
3919 - $ref: '#/components/schemas/id'
3920 description: Video channel in which the playlist will be published
3925 contentType: image/jpeg
3927 /api/v1/video-playlists/{playlistId}:
3929 summary: Get a video playlist
3933 - $ref: '#/components/parameters/playlistId'
3936 description: successful operation
3940 $ref: '#/components/schemas/VideoPlaylist'
3942 summary: Update a video playlist
3943 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3950 description: successful operation
3952 - $ref: '#/components/parameters/playlistId'
3955 multipart/form-data:
3960 description: Video playlist display name
3965 description: Video playlist thumbnail file
3969 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3971 description: Video playlist description
3975 - $ref: '#/components/schemas/id'
3976 description: Video channel in which the playlist will be published
3979 contentType: image/jpeg
3981 summary: Delete a video playlist
3987 - $ref: '#/components/parameters/playlistId'
3990 description: successful operation
3992 /api/v1/video-playlists/{playlistId}/videos:
3994 summary: 'List videos of a playlist'
3995 operationId: getVideoPlaylistVideos
4000 - $ref: '#/components/parameters/playlistId'
4001 - $ref: '#/components/parameters/start'
4002 - $ref: '#/components/parameters/count'
4005 description: successful operation
4009 $ref: '#/components/schemas/VideoListResponse'
4011 summary: Add a video in a playlist
4012 operationId: addVideoPlaylistVideo
4019 - $ref: '#/components/parameters/playlistId'
4022 description: successful operation
4028 videoPlaylistElement:
4042 - $ref: '#/components/schemas/Video/properties/uuid'
4043 - $ref: '#/components/schemas/Video/properties/id'
4044 description: Video to add in the playlist
4048 description: Start the video at this specific timestamp
4052 description: Stop the video at this specific timestamp
4056 /api/v1/video-playlists/{playlistId}/videos/reorder:
4058 summary: 'Reorder a playlist'
4059 operationId: reorderVideoPlaylist
4065 - $ref: '#/components/parameters/playlistId'
4068 description: successful operation
4077 description: 'Start position of the element to reorder'
4079 insertAfterPosition:
4081 description: 'New position for the block to reorder, to add the block before the first element'
4085 description: 'How many element from `startPosition` to reorder'
4089 - insertAfterPosition
4091 /api/v1/video-playlists/{playlistId}/videos/{playlistElementId}:
4093 summary: Update a playlist element
4094 operationId: putVideoPlaylistVideo
4100 - $ref: '#/components/parameters/playlistId'
4101 - $ref: '#/components/parameters/playlistElementId'
4104 description: successful operation
4114 description: Start the video at this specific timestamp
4118 description: Stop the video at this specific timestamp
4120 summary: Delete an element from a playlist
4121 operationId: delVideoPlaylistVideo
4127 - $ref: '#/components/parameters/playlistId'
4128 - $ref: '#/components/parameters/playlistElementId'
4131 description: successful operation
4133 '/api/v1/users/me/video-playlists/videos-exist':
4135 summary: Check video exists in my playlists
4144 description: The video ids to check
4148 $ref: '#/components/schemas/Video/properties/id'
4151 description: successful operation
4173 '/api/v1/accounts/{name}/video-channels':
4175 summary: List video channels of an account
4180 - $ref: '#/components/parameters/name'
4183 description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
4186 - $ref: '#/components/parameters/start'
4187 - $ref: '#/components/parameters/count'
4188 - $ref: '#/components/parameters/sort'
4191 description: successful operation
4195 $ref: '#/components/schemas/VideoChannelList'
4197 '/api/v1/accounts/{name}/video-channel-syncs':
4199 summary: List the synchronizations of video channels of an account
4205 - $ref: '#/components/parameters/name'
4206 - $ref: '#/components/parameters/start'
4207 - $ref: '#/components/parameters/count'
4208 - $ref: '#/components/parameters/sort'
4211 description: successful operation
4215 $ref: '#/components/schemas/VideoChannelSyncList'
4217 '/api/v1/accounts/{name}/ratings':
4219 summary: List ratings of an account
4225 - $ref: '#/components/parameters/name'
4226 - $ref: '#/components/parameters/start'
4227 - $ref: '#/components/parameters/count'
4228 - $ref: '#/components/parameters/sort'
4232 description: Optionally filter which ratings to retrieve
4240 description: successful operation
4246 $ref: '#/components/schemas/VideoRating'
4248 '/api/v1/videos/{id}/comment-threads':
4250 summary: List threads of a video
4254 - $ref: '#/components/parameters/idOrUUID'
4255 - $ref: '#/components/parameters/start'
4256 - $ref: '#/components/parameters/count'
4257 - $ref: '#/components/parameters/commentsSort'
4260 description: successful operation
4264 $ref: '#/components/schemas/CommentThreadResponse'
4266 summary: Create a thread
4272 - $ref: '#/components/parameters/idOrUUID'
4275 description: successful operation
4279 $ref: '#/components/schemas/CommentThreadPostResponse'
4281 description: video does not exist
4290 - $ref: '#/components/schemas/VideoComment/properties/text'
4296 '/api/v1/videos/{id}/comment-threads/{threadId}':
4298 summary: Get a thread
4302 - $ref: '#/components/parameters/idOrUUID'
4303 - $ref: '#/components/parameters/threadId'
4306 description: successful operation
4310 $ref: '#/components/schemas/VideoCommentThreadTree'
4312 '/api/v1/videos/{id}/comments/{commentId}':
4314 summary: Reply to a thread of a video
4320 - $ref: '#/components/parameters/idOrUUID'
4321 - $ref: '#/components/parameters/commentId'
4324 description: successful operation
4328 $ref: '#/components/schemas/CommentThreadPostResponse'
4330 description: thread or video does not exist
4339 - $ref: '#/components/schemas/VideoComment/properties/text'
4345 summary: Delete a comment or a reply
4351 - $ref: '#/components/parameters/idOrUUID'
4352 - $ref: '#/components/parameters/commentId'
4355 description: successful operation
4357 description: cannot remove comment of another user
4359 description: comment or video does not exist
4361 description: comment is already deleted
4363 '/api/v1/videos/{id}/rate':
4365 summary: Like/dislike a video
4371 - $ref: '#/components/parameters/idOrUUID'
4387 description: successful operation
4389 description: video does not exist
4391 '/api/v1/videos/{id}/hls':
4393 summary: Delete video HLS files
4399 operationId: delVideoHLS
4401 - $ref: '#/components/parameters/idOrUUID'
4404 description: successful operation
4406 description: video does not exist
4407 '/api/v1/videos/{id}/webtorrent':
4409 summary: Delete video WebTorrent files
4415 operationId: delVideoWebTorrent
4417 - $ref: '#/components/parameters/idOrUUID'
4420 description: successful operation
4422 description: video does not exist
4424 '/api/v1/videos/{id}/transcoding':
4426 summary: Create a transcoding job
4432 operationId: createVideoTranscoding
4434 - $ref: '#/components/parameters/idOrUUID'
4450 description: successful operation
4452 description: video does not exist
4454 /api/v1/search/videos:
4458 summary: Search videos
4459 operationId: searchVideos
4464 allowEmptyValue: false
4466 String to search. If the user can make a remote URI search, and the string is an URI then the
4467 PeerTube instance will fetch the remote object and add it to its database. Then,
4468 you can use the REST API to fetch the complete video information and interact with it.
4471 - $ref: '#/components/parameters/categoryOneOf'
4472 - $ref: '#/components/parameters/isLive'
4473 - $ref: '#/components/parameters/tagsOneOf'
4474 - $ref: '#/components/parameters/tagsAllOf'
4475 - $ref: '#/components/parameters/licenceOneOf'
4476 - $ref: '#/components/parameters/languageOneOf'
4477 - $ref: '#/components/parameters/nsfw'
4478 - $ref: '#/components/parameters/isLocal'
4479 - $ref: '#/components/parameters/include'
4480 - $ref: '#/components/parameters/privacyOneOf'
4481 - $ref: '#/components/parameters/uuids'
4482 - $ref: '#/components/parameters/hasHLSFiles'
4483 - $ref: '#/components/parameters/hasWebtorrentFiles'
4484 - $ref: '#/components/parameters/skipCount'
4485 - $ref: '#/components/parameters/start'
4486 - $ref: '#/components/parameters/count'
4487 - $ref: '#/components/parameters/searchTarget'
4488 - $ref: '#/components/parameters/videosSearchSort'
4491 description: Get videos that are published after this date
4497 description: Get videos that are published before this date
4501 - name: originallyPublishedStartDate
4503 description: Get videos that are originally published after this date
4507 - name: originallyPublishedEndDate
4509 description: Get videos that are originally published before this date
4515 description: Get videos that have this minimum duration
4520 description: Get videos that have this maximum duration
4524 'searchTarget === search-index':
4525 $ref: '#/components/callbacks/searchIndex'
4528 description: successful operation
4532 $ref: '#/components/schemas/VideoListResponse'
4534 description: search index unavailable
4536 /api/v1/search/video-channels:
4540 summary: Search channels
4541 operationId: searchChannels
4547 String to search. If the user can make a remote URI search, and the string is an URI then the
4548 PeerTube instance will fetch the remote object and add it to its database. Then,
4549 you can use the REST API to fetch the complete channel information and interact with it.
4552 - $ref: '#/components/parameters/start'
4553 - $ref: '#/components/parameters/count'
4554 - $ref: '#/components/parameters/searchTarget'
4555 - $ref: '#/components/parameters/sort'
4557 'searchTarget === search-index':
4558 $ref: '#/components/callbacks/searchIndex'
4561 description: successful operation
4565 $ref: '#/components/schemas/VideoChannelList'
4567 description: search index unavailable
4569 /api/v1/search/video-playlists:
4573 summary: Search playlists
4574 operationId: searchPlaylists
4580 String to search. If the user can make a remote URI search, and the string is an URI then the
4581 PeerTube instance will fetch the remote object and add it to its database. Then,
4582 you can use the REST API to fetch the complete playlist information and interact with it.
4585 - $ref: '#/components/parameters/start'
4586 - $ref: '#/components/parameters/count'
4587 - $ref: '#/components/parameters/searchTarget'
4588 - $ref: '#/components/parameters/sort'
4590 'searchTarget === search-index':
4591 $ref: '#/components/callbacks/searchIndex'
4594 description: successful operation
4606 $ref: '#/components/schemas/VideoPlaylist'
4608 description: search index unavailable
4610 /api/v1/blocklist/status:
4615 summary: Get block status of accounts/hosts
4620 description: 'Check if these accounts are blocked'
4621 example: [ 'goofy@example.com', 'donald@example.com' ]
4629 description: 'Check if these hosts are blocked'
4630 example: [ 'example.com' ]
4637 description: successful operation
4641 $ref: '#/components/schemas/BlockStatus'
4643 /api/v1/server/blocklist/accounts:
4647 summary: List account blocks
4652 - $ref: '#/components/parameters/start'
4653 - $ref: '#/components/parameters/count'
4654 - $ref: '#/components/parameters/sort'
4657 description: successful operation
4661 summary: Block an account
4673 example: chocobozzz@example.org
4674 description: account to block, in the form `username@domain`
4679 description: successful operation
4681 description: self-blocking forbidden
4683 '/api/v1/server/blocklist/accounts/{accountName}':
4687 summary: Unblock an account by its handle
4695 description: account to unblock, in the form `username@domain`
4700 description: successful operation
4702 description: account or account block does not exist
4704 /api/v1/server/blocklist/servers:
4708 summary: List server blocks
4713 - $ref: '#/components/parameters/start'
4714 - $ref: '#/components/parameters/count'
4715 - $ref: '#/components/parameters/sort'
4718 description: successful operation
4722 summary: Block a server
4735 description: server domain to block
4740 description: successful operation
4742 description: self-blocking forbidden
4744 '/api/v1/server/blocklist/servers/{host}':
4748 summary: Unblock a server by its domain
4756 description: server domain to unblock
4762 description: successful operation
4764 description: account block does not exist
4766 /api/v1/server/redundancy/{host}:
4769 - Instance Redundancy
4770 summary: Update a server redundancy policy
4778 description: server domain to mirror
4790 description: allow mirroring of the host's local videos
4795 description: successful operation
4797 description: server is not already known
4799 /api/v1/server/redundancy/videos:
4803 summary: List videos being mirrored
4804 operationId: getMirroredVideos
4812 description: direction of the mirror
4818 - $ref: '#/components/parameters/start'
4819 - $ref: '#/components/parameters/count'
4820 - $ref: '#/components/parameters/videoRedundanciesSort'
4823 description: successful operation
4829 $ref: '#/components/schemas/VideoRedundancy'
4833 summary: Mirror a video
4834 operationId: putMirroredVideo
4845 $ref: '#/components/schemas/Video/properties/id'
4850 description: successful operation
4852 description: cannot mirror a local video
4854 description: video does not exist
4856 description: video is already mirrored
4858 /api/v1/server/redundancy/videos/{redundancyId}:
4862 summary: Delete a mirror done on a video
4863 operationId: delMirroredVideo
4868 - name: redundancyId
4871 description: id of an existing redundancy on a video
4876 description: successful operation
4878 description: video redundancy not found
4880 /api/v1/server/stats:
4884 summary: Get instance stats
4885 description: Get instance public statistics. This endpoint is cached.
4886 operationId: getInstanceStats
4889 description: successful operation
4893 $ref: '#/components/schemas/ServerStats'
4895 /api/v1/server/logs/client:
4899 summary: Send client log
4900 operationId: sendClientLog
4905 $ref: '#/components/schemas/SendClientLog'
4908 description: successful operation
4910 /api/v1/server/logs:
4914 summary: Get instance logs
4915 operationId: getInstanceLogs
4921 description: successful operation
4929 /api/v1/server/audit-logs:
4933 summary: Get instance audit logs
4934 operationId: getInstanceAuditLogs
4940 description: successful operation
4952 summary: List plugins
4953 operationId: getPlugins
4966 - $ref: '#/components/parameters/start'
4967 - $ref: '#/components/parameters/count'
4968 - $ref: '#/components/parameters/sort'
4971 description: successful operation
4975 $ref: '#/components/schemas/PluginResponse'
4977 /api/v1/plugins/available:
4981 summary: List available plugins
4982 operationId: getAvailablePlugins
4995 - name: currentPeerTubeEngine
4999 - $ref: '#/components/parameters/start'
5000 - $ref: '#/components/parameters/count'
5001 - $ref: '#/components/parameters/sort'
5004 description: successful operation
5008 $ref: '#/components/schemas/PluginResponse'
5010 description: plugin index unavailable
5012 /api/v1/plugins/install:
5016 summary: Install a plugin
5017 operationId: addPlugin
5030 example: peertube-plugin-auth-ldap
5033 additionalProperties: false
5040 additionalProperties: false
5043 description: successful operation
5045 description: should have either `npmName` or `path` set
5047 /api/v1/plugins/update:
5051 summary: Update a plugin
5052 operationId: updatePlugin
5065 example: peertube-plugin-auth-ldap
5068 additionalProperties: false
5075 additionalProperties: false
5078 description: successful operation
5080 description: should have either `npmName` or `path` set
5082 description: existing plugin not found
5084 /api/v1/plugins/uninstall:
5088 summary: Uninstall a plugin
5089 operationId: uninstallPlugin
5101 description: name of the plugin/theme in its package.json
5102 example: peertube-plugin-auth-ldap
5107 description: successful operation
5109 description: existing plugin not found
5111 /api/v1/plugins/{npmName}:
5115 summary: Get a plugin
5116 operationId: getPlugin
5121 - $ref: '#/components/parameters/npmName'
5124 description: successful operation
5128 $ref: '#/components/schemas/Plugin'
5130 description: plugin not found
5132 /api/v1/plugins/{npmName}/settings:
5136 summary: Set a plugin's settings
5141 - $ref: '#/components/parameters/npmName'
5150 additionalProperties: true
5153 description: successful operation
5155 description: plugin not found
5157 /api/v1/plugins/{npmName}/public-settings:
5161 summary: Get a plugin's public settings
5163 - $ref: '#/components/parameters/npmName'
5166 description: successful operation
5171 additionalProperties: true
5173 description: plugin not found
5175 /api/v1/plugins/{npmName}/registered-settings:
5179 summary: Get a plugin's registered settings
5184 - $ref: '#/components/parameters/npmName'
5187 description: successful operation
5192 additionalProperties: true
5194 description: plugin not found
5196 /api/v1/metrics/playback:
5198 summary: Create playback metrics
5199 description: These metrics are exposed by OpenTelemetry metrics exporter if enabled.
5206 $ref: '#/components/schemas/PlaybackMetricCreate'
5209 description: successful operation
5212 - url: 'https://peertube2.cpy.re'
5213 description: Live Test Server (live data - latest nightly version)
5214 - url: 'https://peertube3.cpy.re'
5215 description: Live Test Server (live data - latest RC version)
5216 - url: 'https://peertube.cpy.re'
5217 description: Live Test Server (live data - stable version)
5224 description: Offset used to paginate results
5232 description: "Number of items to return"
5242 description: Sort column
5250 description: Plain text search, applied to various parts of the model depending on endpoint
5258 If the administrator enabled search index support, you can override the default search target.
5261 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
5262 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
5263 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
5264 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
5265 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
5266 * 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
5267 the data from the origin instance API
5290 Sort videos by criteria (prefixing with `-` means `DESC` order):
5291 * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
5292 * `best` - Same than `hot`, but also takes into account user video history
5293 * `trending` - Sort videos by recent views ("recent" is defined by the admin)
5294 * `views` - Sort videos using their `views` counter
5295 * `publishedAt` - Sort by video publication date (when it became publicly available)
5301 Sort videos by criteria (prefixing with `-` means `DESC` order):
5316 description: Sort comments by criteria
5326 description: Sort blocklists by criteria
5342 description: Plain text search that will match with user usernames or emails
5349 description: Filter results down to (un)banned users
5356 description: Sort users by criteria
5367 description: Sort abuses by criteria
5374 videoRedundanciesSort:
5378 description: Sort abuses by criteria
5387 description: Sort followers by criteria
5396 description: The username or handle of the account
5399 example: chocobozzz | chocobozzz@example.org
5404 description: Entity id
5406 $ref: '#/components/schemas/id'
5411 description: The object id, uuid or short uuid
5414 - $ref: '#/components/schemas/id'
5415 - $ref: '#/components/schemas/UUIDv4'
5416 - $ref: '#/components/schemas/shortUUID'
5421 description: Playlist id
5423 $ref: '#/components/schemas/VideoPlaylist/properties/id'
5425 name: playlistElementId
5428 description: Playlist element id
5430 $ref: '#/components/schemas/id'
5435 description: Abuse id
5437 $ref: '#/components/schemas/Abuse/properties/id'
5439 name: abuseMessageId
5442 description: Abuse message id
5444 $ref: '#/components/schemas/AbuseMessage/properties/id'
5446 name: captionLanguage
5449 description: The caption language
5451 $ref: '#/components/schemas/VideoLanguageSet'
5456 description: The video channel handle
5459 example: my_username | my_username@example.com
5464 description: Channel Sync id
5466 $ref: '#/components/schemas/Abuse/properties/id'
5468 name: subscriptionHandle
5471 description: The subscription handle
5474 example: my_username | my_username@example.com
5479 description: The thread id (root comment id)
5486 description: The comment id
5488 $ref: '#/components/schemas/VideoComment/properties/id'
5493 description: whether or not the video is a live
5500 description: category id of the video (see [/videos/categories](#operation/getCategories))
5503 - $ref: '#/components/schemas/VideoCategorySet'
5506 $ref: '#/components/schemas/VideoCategorySet'
5513 description: tag(s) of the video
5527 description: tag(s) of the video, where all should be present in the video
5540 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
5543 - $ref: '#/components/schemas/VideoLanguageSet'
5546 $ref: '#/components/schemas/VideoLanguageSet'
5553 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5556 - $ref: '#/components/schemas/VideoLicenceSet'
5559 $ref: '#/components/schemas/VideoLicenceSet'
5566 description: if you don't need the `total` in the response
5577 description: whether to include nsfw videos, if any
5589 description: '**PeerTube >= 4.0** Display only local or remote videos'
5596 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
5598 name: hasWebtorrentFiles
5603 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
5609 $ref: '#/components/schemas/VideoPrivacySet'
5610 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
5618 description: 'Find videos with specific UUIDs'
5632 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
5636 - `1` NOT_PUBLISHED_STATE
5647 description: list of uris to check if each is part of the user subscriptions
5657 description: name of the plugin/theme on npmjs.com or in its package.json
5660 example: peertube-plugin-auth-ldap
5665 description: job type
5669 - activitypub-follow
5670 - activitypub-http-broadcast
5671 - activitypub-http-fetcher
5672 - activitypub-http-unicast
5677 - videos-views-stats
5678 - activitypub-refresher
5681 - video-channel-import
5705 description: Filename
5709 name: videoFileToken
5712 description: Video file token [generated](#operation/requestVideoToken) by PeerTube so you don't need to provide an OAuth token in the request header.
5715 reinjectVideoFileToken:
5716 name: reinjectVideoFileToken
5719 description: Ask the server to reinject videoFileToken in URLs in m3u8 playlist
5726 Authenticating via OAuth requires the following steps:
5727 - Have an activated account
5728 - [Generate] an access token for that account at `/api/v1/users/token`.
5729 - Make requests with the *Authorization: Bearer <token\>* header
5730 - Profit, depending on the role assigned to the account
5732 Note that the __access token is valid for 1 day__ and is given
5733 along with a __refresh token valid for 2 weeks__.
5735 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5739 tokenUrl: /api/v1/users/token
5742 moderator: Moderator scope
5745 # Reusable core properties
5753 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5754 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5759 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5760 example: 2y84q2MQUMWPbiEcxNXMgC
5763 description: immutable name of the user, used to find or mention its actor
5765 pattern: '/^[a-z0-9._]+$/'
5770 description: immutable name of the channel, used to interact with its actor
5771 example: framasoft_videos
5772 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5783 description: category id of the video (see [/videos/categories](#operation/getCategories))
5785 VideoConstantNumber-Category:
5788 $ref: '#/components/schemas/VideoCategorySet'
5791 example: Science & Technology
5795 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5797 VideoConstantNumber-Licence:
5800 $ref: '#/components/schemas/VideoLicenceSet'
5803 example: Attribution - Share Alike
5807 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5809 VideoConstantString-Language:
5812 $ref: '#/components/schemas/VideoLanguageSet'
5817 VideoPlaylistPrivacySet:
5823 description: Video playlist privacy policy (see [/video-playlists/privacies])
5824 VideoPlaylistPrivacyConstant:
5827 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5831 VideoPlaylistTypeSet:
5836 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5837 VideoPlaylistTypeConstant:
5840 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5851 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5852 VideoPrivacyConstant:
5855 $ref: '#/components/schemas/VideoPrivacySet'
5863 additionalProperties:
5864 x-additionalPropertiesName: account
5873 additionalProperties:
5874 x-additionalPropertiesName: host
5895 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5902 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5905 LiveVideoLatencyMode:
5911 description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
5932 - `4`: Waiting for live stream
5934 - `6`: To move to an external storage (object storage...)
5935 - `7`: Transcoding failed
5936 - `8`: Moving to an external storage failed
5937 - `9`: To edit using studio edition feature
5947 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5951 $ref: '#/components/schemas/AbuseStateSet'
5954 AbusePredefinedReasons:
5967 example: [spamOrMisleading]
5972 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5974 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5976 VideoResolutionConstant:
5977 description: resolutions and their labels for the video
5980 $ref: '#/components/schemas/VideoResolutionSet'
5984 VideoScheduledUpdate:
5987 $ref: '#/components/schemas/VideoPrivacySet'
5991 description: When to update the video
6011 $ref: '#/components/schemas/ActorImage'
6012 VideoChannelSummary:
6015 $ref: '#/components/schemas/id'
6029 $ref: '#/components/schemas/ActorImage'
6043 - $ref: '#/components/schemas/Video'
6048 $ref: '#/components/schemas/id'
6052 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
6053 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6055 $ref: '#/components/schemas/VideoResolutionConstant'
6058 description: Video file size in bytes
6061 description: Direct URL of the torrent file
6065 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
6069 description: Direct URL of the video
6073 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
6077 description: Frames per second of the video file
6081 description: URL dereferencing the output of ffprobe on the file
6082 VideoStreamingPlaylists:
6087 $ref: '#/components/schemas/id'
6095 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
6096 VideoStreamingPlaylists-HLS:
6107 Video files associated to this playlist.
6109 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
6111 $ref: '#/components/schemas/VideoFile'
6123 $ref: '#/components/schemas/Video/properties/id'
6125 $ref: '#/components/schemas/Video/properties/uuid'
6127 $ref: '#/components/schemas/Video/properties/name'
6131 description: object id for the video
6133 - $ref: '#/components/schemas/id'
6135 description: universal identifier for the video, that can be used across instances
6137 - $ref: '#/components/schemas/UUIDv4'
6140 - $ref: '#/components/schemas/shortUUID'
6146 example: 2017-10-01T10:52:46.396Z
6147 description: time at which the video object was first drafted
6151 example: 2018-10-01T10:52:46.396Z
6152 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
6156 example: 2021-05-04T08:01:01.502Z
6157 description: last time the video's metadata was modified
6158 originallyPublishedAt:
6161 example: 2010-10-01T10:52:46.396Z
6162 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
6165 - $ref: '#/components/schemas/VideoConstantNumber-Category'
6166 description: category in which the video is classified
6169 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
6170 description: licence under which the video is distributed
6173 - $ref: '#/components/schemas/VideoConstantString-Language'
6174 description: main language used in the video
6177 - $ref: '#/components/schemas/VideoPrivacyConstant'
6178 description: privacy policy used to distribute the video
6182 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
6183 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
6187 truncated description of the video, written in Markdown.
6188 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
6193 description: duration of the video in seconds
6198 description: title of the video
6199 example: What is PeerTube?
6204 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
6207 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
6210 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
6227 - $ref: '#/components/schemas/VideoStateConstant'
6228 description: represents the internal state of the video processing within the PeerTube instance
6232 - $ref: '#/components/schemas/VideoScheduledUpdate'
6240 $ref: '#/components/schemas/AccountSummary'
6242 $ref: '#/components/schemas/VideoChannelSummary'
6251 - $ref: '#/components/schemas/Video'
6256 description: If the video is a live, you have the amount of current viewers
6259 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
6260 description: path at which to get the full description of maximum `10000` characters
6263 description: A text tell the audience how to support the video creator
6264 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6268 $ref: '#/components/schemas/VideoChannel'
6270 $ref: '#/components/schemas/Account'
6272 example: [flowers, gardening]
6290 - https://peertube2.cpy.re/tracker/announce
6291 - wss://peertube2.cpy.re/tracker/socket
6295 $ref: '#/components/schemas/VideoFile'
6297 WebTorrent/raw video files. If WebTorrent is disabled on the server:
6299 - field will be empty
6300 - video files will be found in `streamingPlaylists[].files` field
6304 $ref: '#/components/schemas/VideoStreamingPlaylists'
6306 HLS playlists/manifest files. If HLS is disabled on the server:
6308 - field will be empty
6309 - video files will be found in `files` field
6310 FileRedundancyInformation:
6313 $ref: '#/components/schemas/id'
6338 $ref: '#/components/schemas/id'
6345 $ref: '#/components/schemas/UUIDv4'
6352 $ref: '#/components/schemas/FileRedundancyInformation'
6356 $ref: '#/components/schemas/FileRedundancyInformation'
6357 VideoImportStateConstant:
6365 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
6372 additionalProperties: false
6376 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
6377 required: [targetUrl]
6380 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6381 required: [magnetUri]
6384 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
6385 required: [torrentfile]
6386 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6395 - $ref: '#/components/schemas/id'
6399 description: remote URL where to find the import's source video
6400 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
6404 description: magnet URI allowing to resolve the import's source video
6405 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6410 description: Torrent file containing only the video file
6417 - $ref: '#/components/schemas/VideoImportStateConstant'
6433 - $ref: '#/components/schemas/Video'
6443 $ref: '#/components/schemas/VideoImport'
6447 $ref: '#/components/schemas/id'
6450 example: The video is a spam
6454 $ref: '#/components/schemas/AbusePredefinedReasons'
6456 $ref: '#/components/schemas/Account'
6458 $ref: '#/components/schemas/AbuseStateConstant'
6461 example: Decided to ban the server since it spams us regularly
6465 $ref: '#/components/schemas/VideoInfo'
6472 $ref: '#/components/schemas/id'
6483 $ref: '#/components/schemas/AccountSummary'
6487 $ref: '#/components/schemas/id'
6489 $ref: '#/components/schemas/Video/properties/id'
6501 $ref: '#/components/schemas/UUIDv4'
6519 $ref: '#/components/schemas/id'
6521 $ref: '#/components/schemas/UUIDv4'
6524 - $ref: '#/components/schemas/shortUUID'
6547 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
6549 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
6551 $ref: '#/components/schemas/AccountSummary'
6553 $ref: '#/components/schemas/VideoChannelSummary'
6557 $ref: '#/components/schemas/id'
6564 description: Text of the comment
6566 example: This video is wonderful!
6568 $ref: '#/components/schemas/id'
6572 - $ref: '#/components/schemas/id'
6574 $ref: '#/components/schemas/Video/properties/id'
6589 totalRepliesFromVideoAuthor:
6596 $ref: '#/components/schemas/Account'
6597 VideoCommentThreadTree:
6600 $ref: '#/components/schemas/VideoComment'
6604 $ref: '#/components/schemas/VideoCommentThreadTree'
6608 $ref: '#/components/schemas/VideoConstantString-Language'
6630 $ref: '#/components/schemas/id'
6641 $ref: '#/components/schemas/ActorImage'
6645 $ref: '#/components/schemas/id'
6650 description: immutable name of the actor, used to find or mention it
6652 - $ref: '#/components/schemas/username'
6656 description: server on which the actor is resident
6657 hostRedundancyAllowed:
6659 description: whether this actor's host allows redundancy of its videos
6663 description: number of actors subscribed to by this actor, as seen by this instance
6667 description: number of followers of this actor, as seen by this instance
6676 - $ref: '#/components/schemas/Actor'
6679 description: object id for the user tied to this account
6681 - $ref: '#/components/schemas/User/properties/id'
6684 description: editable name of the account, displayed in its representations
6689 description: text or bio displayed on the account's profile
6697 description: timestamp within the video, in seconds
6704 Event since last viewing call:
6705 * `seek` - If the user seeked the video
6728 VideoStatsRetention:
6740 VideoStatsTimeserie:
6817 allowedForCurrentIP:
6819 requiresEmailVerification:
6837 $ref: '#/components/schemas/VideoResolutionSet'
6854 videoChannelSynchronization:
6927 example: 16810141515
6968 description: URL of the current user page
6975 description: Stack trace of the error if there is one
6978 description: User agent of the web browser that sends the message
6981 description: Additional information regarding this log
6991 totalDailyActiveUsers:
6993 totalWeeklyActiveUsers:
6995 totalMonthlyActiveUsers:
6999 totalLocalVideoViews:
7001 description: Total video views made on the instance
7002 totalLocalVideoComments:
7004 description: Total comments made by local users
7005 totalLocalVideoFilesSize:
7011 totalLocalVideoChannels:
7013 totalLocalDailyActiveVideoChannels:
7015 totalLocalWeeklyActiveVideoChannels:
7017 totalLocalMonthlyActiveVideoChannels:
7019 totalLocalPlaylists:
7021 totalInstanceFollowers:
7023 totalInstanceFollowing:
7040 totalActivityPubMessagesProcessed:
7042 totalActivityPubMessagesSuccesses:
7044 totalActivityPubMessagesErrors:
7047 activityPubMessagesProcessedPerSecond:
7049 totalActivityPubMessagesWaiting:
7126 requiresEmailVerification:
7141 description: Settings that apply to new users, if registration is enabled
7145 example: 16810141515
7151 description: Settings pertaining to transcoding jobs
7155 allowAdditionalExtensions:
7157 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
7160 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
7163 description: Amount of threads used by ffmpeg for 1 transcoding job
7166 description: Amount of transcoding jobs to execute in parallel
7172 New profiles can be added by plugins ; available in core PeerTube: 'default'.
7175 description: Resolutions to transcode _new videos_ to
7197 description: WebTorrent-specific settings
7203 description: HLS-specific settings
7223 video_channel_synchronization:
7258 $ref: '#/components/schemas/id'
7260 $ref: '#/components/schemas/Actor'
7262 $ref: '#/components/schemas/Actor'
7265 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
7278 PredefinedAbuseReasons:
7279 description: Reason categories that help triage reports
7297 $ref: '#/components/schemas/id'
7309 - activitypub-http-unicast
7310 - activitypub-http-broadcast
7311 - activitypub-http-fetcher
7312 - activitypub-follow
7317 - videos-views-stats
7318 - activitypub-refresher
7320 - video-channel-import
7323 additionalProperties: true
7326 additionalProperties: true
7342 $ref: '#/components/schemas/id'
7347 $ref: '#/components/schemas/id'
7348 VideoUploadRequestCommon:
7351 description: Video name
7353 example: What is PeerTube?
7357 description: Channel id that will contain this video
7362 $ref: '#/components/schemas/VideoPrivacySet'
7364 $ref: '#/components/schemas/VideoCategorySet'
7366 $ref: '#/components/schemas/VideoLicenceSet'
7368 $ref: '#/components/schemas/VideoLanguageSet'
7370 description: Video description
7373 **[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)**
7375 description: Whether or not we wait transcoding before publish the video
7378 description: A text tell the audience how to support the video creator
7379 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7382 description: Whether or not this video contains sensitive content
7385 description: Video tags (maximum 5 tags each between 2 and 30 characters)
7398 description: Enable or disable comments for this video
7401 description: Enable or disable downloading for this video
7403 originallyPublishedAt:
7404 description: Date when the content was originally published
7408 $ref: '#/components/schemas/VideoScheduledUpdate'
7410 description: Video thumbnail file
7414 description: Video preview file
7420 VideoUploadRequestLegacy:
7422 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7428 description: Video file
7431 VideoUploadRequestResumable:
7433 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7439 description: Video filename including extension
7442 example: what_is_peertube.mp4
7444 description: Video thumbnail file
7448 description: Video preview file
7451 VideoUploadResponse:
7457 $ref: '#/components/schemas/Video/properties/id'
7459 $ref: '#/components/schemas/Video/properties/uuid'
7461 $ref: '#/components/schemas/Video/properties/shortUUID'
7462 CommentThreadResponse:
7471 $ref: '#/components/schemas/VideoComment'
7472 CommentThreadPostResponse:
7475 $ref: '#/components/schemas/VideoComment'
7495 $ref: '#/components/schemas/Video'
7499 $ref: '#/components/schemas/Account'
7502 description: Automatically start playing the upcoming video after the currently playing video
7503 autoPlayNextVideoPlaylist:
7505 description: Automatically start playing the video on the playlist after the currently playing video
7508 description: Automatically start playing the video on the watch page
7518 description: The user email
7521 description: Has the user confirmed their email address?
7524 - $ref: '#/components/schemas/id'
7528 description: Auth plugin to use to authenticate the user
7532 noInstanceConfigWarningModal:
7534 noAccountSetupWarningModal:
7539 $ref: '#/components/schemas/NSFWPolicy'
7544 $ref: '#/components/schemas/UserRole'
7553 description: Theme enabled by this user
7555 $ref: '#/components/schemas/username'
7559 $ref: '#/components/schemas/VideoChannel'
7562 description: The user video quota in bytes
7566 description: The user daily video quota in bytes
7570 description: Enable P2P in the player
7573 - $ref: '#/components/schemas/User'
7575 # optionally present fields: they require WITH_STATS scope
7578 description: Count of videos published
7581 description: Count of reports/abuses of which the user is a target
7582 abusesAcceptedCount:
7584 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
7587 description: Count of reports/abuses created by the user
7590 description: Count of comments published
7594 $ref: '#/components/schemas/username'
7596 $ref: '#/components/schemas/password'
7600 description: The user email
7603 description: The user video quota in bytes
7607 description: The user daily video quota in bytes
7610 $ref: '#/components/schemas/usernameChannel'
7612 $ref: '#/components/schemas/UserRole'
7614 $ref: '#/components/schemas/UserAdminFlags'
7625 description: The updated email of the user
7627 - $ref: '#/components/schemas/User/properties/email'
7630 description: Set the email as verified
7633 description: The updated video quota of the user in bytes
7636 description: The updated daily video quota of the user in bytes
7640 description: The auth plugin to use to authenticate the user
7641 example: 'peertube-plugin-auth-saml2'
7643 $ref: '#/components/schemas/UserRole'
7645 $ref: '#/components/schemas/UserAdminFlags'
7647 $ref: '#/components/schemas/password'
7649 # see shared/models/users/user-update-me.model.ts:
7652 $ref: '#/components/schemas/password'
7654 $ref: '#/components/schemas/password'
7656 description: new email used for login and service communications
7658 - $ref: '#/components/schemas/User/properties/email'
7661 description: new name of the user in its representations
7666 description: new NSFW display policy
7673 description: whether to enable P2P in the player or not
7676 description: new preference regarding playing videos automatically
7679 description: new preference regarding playing following videos automatically
7680 autoPlayNextVideoPlaylist:
7682 description: new preference regarding playing following playlist videos automatically
7683 videosHistoryEnabled:
7685 description: whether to keep track of watched history or not
7690 description: list of languages to filter videos down to
7693 noInstanceConfigWarningModal:
7695 noAccountSetupWarningModal:
7702 $ref: '#/components/schemas/id'
7709 description: Rating of the video
7716 $ref: '#/components/schemas/Video'
7723 description: Rating of the video
7730 description: immutable name of the user, used to find or mention its actor
7732 - $ref: '#/components/schemas/username'
7734 $ref: '#/components/schemas/password'
7738 description: email of the user, used for login or service communications
7741 description: editable name of the user, displayed in its representations
7746 description: channel base information used to create the first channel of the user
7749 $ref: '#/components/schemas/usernameChannel'
7761 pattern: /^[a-z0-9]$/
7764 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
7767 pattern: /^[a-zA-Z0-9]$/
7770 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
7771 OAuthToken-password:
7773 - $ref: '#/components/schemas/OAuthClient'
7783 $ref: '#/components/schemas/User/properties/username'
7785 $ref: '#/components/schemas/password'
7792 OAuthToken-refresh_token:
7794 - $ref: '#/components/schemas/OAuthClient'
7805 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
7814 - $ref: '#/components/schemas/Actor'
7819 description: editable name of the channel, displayed in its representations
7820 example: Videos of Framasoft
7825 example: Videos made with <3 by Framasoft
7830 description: text shown by default on all videos of this channel, to tell the audience how to support it
7831 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7844 $ref: '#/components/schemas/ActorImage'
7853 $ref: '#/components/schemas/UUIDv4'
7857 - $ref: '#/components/schemas/VideoChannel'
7860 description: username of the channel to create
7862 - $ref: '#/components/schemas/usernameChannel'
7868 - $ref: '#/components/schemas/VideoChannel'
7870 bulkVideosSupportUpdate:
7872 description: Update the support field for all videos of this channel
7882 - $ref: '#/components/schemas/VideoChannel'
7883 - $ref: '#/components/schemas/Actor'
7885 ImportVideosInChannelCreate:
7890 example: https://youtube.com/c/UC_myfancychannel
7893 description: If part of a channel sync process, specify its id to assign video imports to this channel synchronization
7895 - 'externalChannelUrl'
7901 $ref: '#/components/schemas/id'
7913 example: 'https://youtube.com/c/UC_myfancychannel'
7922 $ref: '#/components/schemas/VideoChannel'
7923 VideoChannelSyncList:
7933 - $ref: '#/components/schemas/VideoChannelSync'
7934 VideoChannelSyncCreate:
7939 example: https://youtube.com/c/UC_myfancychannel
7941 $ref: '#/components/schemas/id'
7945 name: 'media:peerLink'
7954 - application/x-bittorrent
7960 name: 'media:content'
7991 VideoCommentsForXML:
8026 description: video watch page URL
8029 description: video canonical URL
8033 description: video publication date
8036 description: video description
8039 description: video description
8042 description: publisher user name
8045 description: video category (MRSS)
8048 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
8063 description: video embed path, relative to the canonical URL domain (MRSS)
8072 description: video watch path, relative to the canonical URL domain (MRSS)
8093 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
8094 'media:description':
8101 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
8104 description: main streamable file for the video
8114 - application/x-bittorrent
8123 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)
8126 - $ref: '#/components/schemas/MRSSPeerLink'
8127 - $ref: '#/components/schemas/MRSSGroupContent'
8128 NotificationSettingValue:
8131 Notification type. One of the following values, or a sum of multiple values:
8141 $ref: '#/components/schemas/id'
8145 Notification type, following the `UserNotificationType` enum:
8147 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
8149 - `2` NEW_COMMENT_ON_MY_VIDEO
8151 - `3` NEW_ABUSE_FOR_MODERATORS
8153 - `4` BLACKLIST_ON_MY_VIDEO
8155 - `5` UNBLACKLIST_ON_MY_VIDEO
8157 - `6` MY_VIDEO_PUBLISHED
8159 - `7` MY_VIDEO_IMPORT_SUCCESS
8161 - `8` MY_VIDEO_IMPORT_ERROR
8163 - `9` NEW_USER_REGISTRATION
8167 - `11` COMMENT_MENTION
8169 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
8171 - `13` NEW_INSTANCE_FOLLOWER
8173 - `14` AUTO_INSTANCE_FOLLOWING
8175 - `15` ABUSE_STATE_CHANGE
8177 - `16` ABUSE_NEW_MESSAGE
8179 - `17` NEW_PLUGIN_VERSION
8181 - `18` NEW_PEERTUBE_VERSION
8187 - $ref: '#/components/schemas/VideoInfo'
8191 $ref: '#/components/schemas/ActorInfo'
8197 $ref: '#/components/schemas/id'
8200 $ref: '#/components/schemas/VideoInfo'
8205 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
8215 $ref: '#/components/schemas/id'
8219 $ref: '#/components/schemas/VideoInfo'
8221 $ref: '#/components/schemas/ActorInfo'
8227 $ref: '#/components/schemas/id'
8230 - $ref: '#/components/schemas/VideoInfo'
8236 $ref: '#/components/schemas/id'
8239 - $ref: '#/components/schemas/VideoInfo'
8243 - $ref: '#/components/schemas/ActorInfo'
8249 $ref: '#/components/schemas/id'
8251 $ref: '#/components/schemas/ActorInfo'
8279 NotificationListResponse:
8288 $ref: '#/components/schemas/Notification'
8293 example: peertube-plugin-auth-ldap
8321 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
8324 additionalProperties: true
8340 $ref: '#/components/schemas/Plugin'
8347 description: User can stream multiple times in a permanent live
8350 description: User can select live latency mode if enabled by the instance
8351 $ref: '#/components/schemas/LiveVideoLatencyMode'
8357 description: Included in the response if an appropriate token is provided
8360 description: Included in the response if an appropriate token is provided
8363 description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
8367 description: User can stream multiple times in a permanent live
8370 description: User can select live latency mode if enabled by the instance
8371 $ref: '#/components/schemas/LiveVideoLatencyMode'
8373 RequestTwoFactorResponse:
8380 description: The token to send to confirm this request
8383 description: The OTP secret
8386 description: The OTP URI
8388 VideoStudioCreateTask:
8436 title: add-watermark
8450 LiveVideoSessionResponse:
8457 description: Start date of the live session
8462 description: End date of the live session
8473 Error type if an error occurred during the live session:
8474 - `1`: Bad socket health (transcoding is too slow)
8475 - `2`: Max duration exceeded
8476 - `3`: Quota exceeded
8477 - `4`: Quota FFmpeg error
8478 - `5`: Video has been blacklisted during the live
8481 description: Video replay information
8486 $ref: '#/components/schemas/UUIDv4'
8488 $ref: '#/components/schemas/shortUUID'
8490 PlaybackMetricCreate:
8495 - 'p2p-media-loader'
8499 description: Current player video resolution
8502 description: Current player video fps
8505 description: How many resolution changes occured since the last metric creation
8508 description: How many errors occured since the last metric creation
8511 description: How many bytes were downloaded with P2P since the last metric creation
8512 downloadedBytesHTTP:
8514 description: How many bytes were downloaded with HTTP since the last metric creation
8517 description: How many bytes were uploaded with P2P since the last metric creation
8520 - $ref: '#/components/schemas/id'
8521 - $ref: '#/components/schemas/UUIDv4'
8522 - $ref: '#/components/schemas/shortUUID'
8527 - downloadedBytesP2P
8528 - downloadedBytesHTTP
8534 'https://search.example.org/api/v1/search/videos':
8536 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
8539 description: successful operation
8543 $ref: '#/components/schemas/VideoListResponse'