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'
415 description: successful operation
417 description: invalid auth
419 description: not found
422 '/feeds/video-comments.{format}':
426 summary: List comments on videos
427 operationId: getSyndicatedComments
432 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
445 description: 'limit listing to a specific video'
450 description: 'limit listing to a specific account'
455 description: 'limit listing to a specific account'
458 - name: videoChannelId
460 description: 'limit listing to a specific video channel'
463 - name: videoChannelName
465 description: 'limit listing to a specific video channel'
470 description: successful operation
475 default: 'max-age=900' # 15 min cache
479 $ref: '#/components/schemas/VideoCommentsForXML'
482 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
485 $ref: '#/components/schemas/VideoCommentsForXML'
488 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
491 $ref: '#/components/schemas/VideoCommentsForXML'
494 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
495 application/atom+xml:
497 $ref: '#/components/schemas/VideoCommentsForXML'
500 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
506 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
508 x-summary: field inconsistencies
511 - videoId filter is mixed with a channel filter
513 description: video, video channel or account not found
515 description: accept header unsupported
517 '/feeds/videos.{format}':
522 operationId: getSyndicatedVideos
527 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
540 description: 'limit listing to a specific account'
545 description: 'limit listing to a specific account'
548 - name: videoChannelId
550 description: 'limit listing to a specific video channel'
553 - name: videoChannelName
555 description: 'limit listing to a specific video channel'
558 - $ref: '#/components/parameters/sort'
559 - $ref: '#/components/parameters/nsfw'
560 - $ref: '#/components/parameters/isLocal'
561 - $ref: '#/components/parameters/include'
562 - $ref: '#/components/parameters/privacyOneOf'
563 - $ref: '#/components/parameters/hasHLSFiles'
564 - $ref: '#/components/parameters/hasWebtorrentFiles'
567 description: successful operation
572 default: 'max-age=900' # 15 min cache
576 $ref: '#/components/schemas/VideosForXML'
579 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
582 $ref: '#/components/schemas/VideosForXML'
585 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
588 $ref: '#/components/schemas/VideosForXML'
591 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
592 application/atom+xml:
594 $ref: '#/components/schemas/VideosForXML'
597 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
603 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
605 description: video channel or account not found
607 description: accept header unsupported
609 '/feeds/subscriptions.{format}':
613 summary: List videos of subscriptions tied to a token
614 operationId: getSyndicatedSubscriptionVideos
619 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
632 description: limit listing to a specific account
638 description: private token allowing access
642 - $ref: '#/components/parameters/sort'
643 - $ref: '#/components/parameters/nsfw'
644 - $ref: '#/components/parameters/isLocal'
645 - $ref: '#/components/parameters/include'
646 - $ref: '#/components/parameters/privacyOneOf'
647 - $ref: '#/components/parameters/hasHLSFiles'
648 - $ref: '#/components/parameters/hasWebtorrentFiles'
651 description: successful operation
656 default: 'max-age=900' # 15 min cache
660 $ref: '#/components/schemas/VideosForXML'
663 $ref: '#/components/schemas/VideosForXML'
666 $ref: '#/components/schemas/VideosForXML'
667 application/atom+xml:
669 $ref: '#/components/schemas/VideosForXML'
674 description: accept header unsupported
676 '/api/v1/accounts/{name}':
680 summary: Get an account
681 operationId: getAccount
683 - $ref: '#/components/parameters/name'
686 description: successful operation
690 $ref: '#/components/schemas/Account'
692 description: account not found
694 '/api/v1/accounts/{name}/videos':
699 summary: 'List videos of an account'
700 operationId: getAccountVideos
702 - $ref: '#/components/parameters/name'
703 - $ref: '#/components/parameters/categoryOneOf'
704 - $ref: '#/components/parameters/isLive'
705 - $ref: '#/components/parameters/tagsOneOf'
706 - $ref: '#/components/parameters/tagsAllOf'
707 - $ref: '#/components/parameters/licenceOneOf'
708 - $ref: '#/components/parameters/languageOneOf'
709 - $ref: '#/components/parameters/nsfw'
710 - $ref: '#/components/parameters/isLocal'
711 - $ref: '#/components/parameters/include'
712 - $ref: '#/components/parameters/privacyOneOf'
713 - $ref: '#/components/parameters/hasHLSFiles'
714 - $ref: '#/components/parameters/hasWebtorrentFiles'
715 - $ref: '#/components/parameters/skipCount'
716 - $ref: '#/components/parameters/start'
717 - $ref: '#/components/parameters/count'
718 - $ref: '#/components/parameters/videosSort'
721 description: successful operation
725 $ref: '#/components/schemas/VideoListResponse'
729 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
730 .then(function(response) {
731 return response.json()
732 }).then(function(data) {
738 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
744 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
746 http = Net::HTTP.new(uri.host, uri.port)
749 response = http.get(uri.request_uri)
751 puts JSON.parse(response.read_body)
756 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
761 '/api/v1/accounts/{name}/followers':
765 summary: 'List followers of an account'
768 operationId: getAccountFollowers
770 - $ref: '#/components/parameters/name'
771 - $ref: '#/components/parameters/start'
772 - $ref: '#/components/parameters/count'
773 - $ref: '#/components/parameters/followersSort'
774 - $ref: '#/components/parameters/search'
777 description: successful operation
789 $ref: '#/components/schemas/Follow'
795 summary: List accounts
796 operationId: getAccounts
798 - $ref: '#/components/parameters/start'
799 - $ref: '#/components/parameters/count'
800 - $ref: '#/components/parameters/sort'
803 description: successful operation
809 $ref: '#/components/schemas/Account'
815 summary: Get instance public configuration
816 operationId: getConfig
819 description: successful operation
823 $ref: '#/components/schemas/ServerConfig'
826 externalValue: https://peertube2.cpy.re/api/v1/config
828 /api/v1/config/about:
830 summary: Get instance "About" information
831 operationId: getAbout
836 description: successful operation
840 $ref: '#/components/schemas/ServerConfigAbout'
843 externalValue: https://peertube2.cpy.re/api/v1/config/about
845 /api/v1/config/custom:
847 summary: Get instance runtime configuration
848 operationId: getCustomConfig
856 description: successful operation
860 $ref: '#/components/schemas/ServerConfigCustom'
862 summary: Set instance runtime configuration
863 operationId: putCustomConfig
871 description: successful operation
873 x-summary: field inconsistencies
876 - the emailer is disabled and the instance is open to registrations
877 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
879 summary: Delete instance runtime configuration
880 operationId: delCustomConfig
888 description: successful operation
890 /api/v1/custom-pages/homepage/instance:
892 summary: Get instance custom homepage
897 description: No homepage set
899 description: successful operation
903 $ref: '#/components/schemas/CustomHomepage'
905 summary: Set instance custom homepage
919 description: content of the homepage, that will be injected in the client
922 description: successful operation
926 summary: Pause job queue
934 description: successful operation
938 summary: Resume job queue
946 description: successful operation
948 /api/v1/jobs/{state}:
950 summary: List instance jobs
961 description: The state of the job ('' for for no filter)
971 - $ref: '#/components/parameters/jobType'
972 - $ref: '#/components/parameters/start'
973 - $ref: '#/components/parameters/count'
974 - $ref: '#/components/parameters/sort'
977 description: successful operation
990 $ref: '#/components/schemas/Job'
992 /api/v1/server/followers:
996 summary: List instances following the server
998 - $ref: '#/components/parameters/followState'
999 - $ref: '#/components/parameters/actorType'
1000 - $ref: '#/components/parameters/start'
1001 - $ref: '#/components/parameters/count'
1002 - $ref: '#/components/parameters/sort'
1005 description: successful operation
1017 $ref: '#/components/schemas/Follow'
1019 '/api/v1/server/followers/{nameWithHost}':
1021 summary: Remove or reject a follower to your server
1028 - name: nameWithHost
1031 description: The remote actor handle to remove from your followers
1037 description: successful operation
1039 description: follower not found
1041 '/api/v1/server/followers/{nameWithHost}/reject':
1043 summary: Reject a pending follower to your server
1050 - name: nameWithHost
1053 description: The remote actor handle to remove from your followers
1059 description: successful operation
1061 description: follower not found
1063 '/api/v1/server/followers/{nameWithHost}/accept':
1065 summary: Accept a pending follower to your server
1072 - name: nameWithHost
1075 description: The remote actor handle to remove from your followers
1081 description: successful operation
1083 description: follower not found
1085 /api/v1/server/following:
1089 summary: List instances followed by the server
1091 - $ref: '#/components/parameters/followState'
1092 - $ref: '#/components/parameters/actorType'
1093 - $ref: '#/components/parameters/start'
1094 - $ref: '#/components/parameters/count'
1095 - $ref: '#/components/parameters/sort'
1098 description: successful operation
1110 $ref: '#/components/schemas/Follow'
1117 summary: Follow a list of actors (PeerTube instance, channel or account)
1120 description: successful operation
1122 description: cannot follow a non-HTTPS server
1141 '/api/v1/server/following/{hostOrHandle}':
1143 summary: Unfollow an actor (PeerTube instance, channel or account)
1150 - name: hostOrHandle
1153 description: The hostOrHandle to unfollow
1158 description: successful operation
1160 description: host or handle not found
1164 summary: Create a user
1165 operationId: addUser
1173 description: user created
1177 $ref: '#/components/schemas/AddUserResponse'
1181 operationId: getUser
1183 id: '$response.body#/user/id'
1186 operationId: putUser
1188 id: '$response.body#/user/id'
1189 # DELETE /users/{id}
1191 operationId: delUser
1193 id: '$response.body#/user/id'
1195 description: insufficient authority to create an admin or moderator
1200 $ref: '#/components/schemas/AddUser'
1202 If the smtp server is configured, you can leave the password empty and an email will be sent
1203 asking the user to set it first.
1207 operationId: getUsers
1214 - $ref: '#/components/parameters/usersSearch'
1215 - $ref: '#/components/parameters/usersBlocked'
1216 - $ref: '#/components/parameters/start'
1217 - $ref: '#/components/parameters/count'
1218 - $ref: '#/components/parameters/usersSort'
1221 description: successful operation
1227 $ref: '#/components/schemas/User'
1229 '/api/v1/users/{id}':
1231 - $ref: '#/components/parameters/id'
1233 summary: Delete a user
1239 operationId: delUser
1242 description: successful operation
1249 operationId: getUser
1253 description: include statistics about the user (only available as a moderator/admin)
1258 x-summary: successful operation
1260 As an admin/moderator, you can request a response augmented with statistics about the user's
1261 moderation relations and videos usage, by using the `withStats` parameter.
1266 - $ref: '#/components/schemas/User'
1267 - $ref: '#/components/schemas/UserWithStats'
1269 summary: Update a user
1274 operationId: putUser
1277 description: successful operation
1282 $ref: '#/components/schemas/UpdateUser'
1285 /api/v1/oauth-clients/local:
1287 summary: Login prerequisite
1288 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
1289 operationId: getOAuthClient
1294 description: successful operation
1298 $ref: '#/components/schemas/OAuthClient'
1300 UseOAuthClientToLogin:
1301 operationId: getOAuthToken
1303 client_id: '$response.body#/client_id'
1304 client_secret: '$response.body#/client_secret'
1308 API="https://peertube2.cpy.re/api/v1"
1311 curl -s "$API/oauth-clients/local"
1313 /api/v1/users/token:
1316 operationId: getOAuthToken
1317 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
1322 application/x-www-form-urlencoded:
1325 - $ref: '#/components/schemas/OAuthToken-password'
1326 - $ref: '#/components/schemas/OAuthToken-refresh_token'
1328 propertyName: grant_type
1330 password: '#/components/schemas/OAuthToken-password'
1331 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
1334 description: successful operation
1345 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
1346 description: valid for 1 day
1349 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
1350 description: valid for 2 weeks
1355 refresh_token_expires_in:
1360 x-summary: client or credentials are invalid
1362 Disambiguate via `type`:
1363 - `invalid_client` for an unmatched `client_id`
1364 - `invalid_grant` for unmatched credentials
1366 x-summary: token expired
1368 Disambiguate via `type`:
1369 - default value for a regular authentication failure
1370 - `invalid_token` for an expired token
1375 API="https://peertube2.cpy.re/api/v1"
1376 USERNAME="<your_username>"
1377 PASSWORD="<your_password>"
1380 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1381 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1382 curl -s "$API/users/token" \
1383 --data client_id="$client_id" \
1384 --data client_secret="$client_secret" \
1385 --data grant_type=password \
1386 --data username="$USERNAME" \
1387 --data password="$PASSWORD" \
1388 | jq -r ".access_token"
1390 /api/v1/users/revoke-token:
1393 description: Revokes your access token and its associated refresh token, destroying your current session.
1394 operationId: revokeOAuthToken
1401 description: successful operation
1403 /api/v1/users/register:
1405 summary: Register a user
1406 operationId: registerUser
1412 description: successful operation
1417 $ref: '#/components/schemas/RegisterUser'
1420 /api/v1/users/{id}/verify-email:
1422 summary: Verify a user
1423 operationId: verifyUser
1425 Following a user registration, the new user will receive an email asking to click a link
1426 containing a secret.
1431 - $ref: '#/components/parameters/id'
1444 - verificationString
1447 description: successful operation
1449 description: invalid verification string
1451 description: user not found
1453 /api/v1/users/{id}/two-factor/request:
1455 summary: Request two factor auth
1456 operationId: requestTwoFactor
1457 description: Request two factor authentication for a user
1461 - $ref: '#/components/parameters/id'
1470 description: Password of the currently authenticated user
1473 description: successful operation
1479 $ref: '#/components/schemas/RequestTwoFactorResponse'
1481 description: invalid password
1483 description: user not found
1485 /api/v1/users/{id}/two-factor/confirm-request:
1487 summary: Confirm two factor auth
1488 operationId: confirmTwoFactorRequest
1489 description: Confirm a two factor authentication request
1493 - $ref: '#/components/parameters/id'
1502 description: Token to identify the two factor request
1505 description: OTP token generated by the app
1511 description: successful operation
1513 description: invalid request token or OTP token
1515 description: user not found
1517 /api/v1/users/{id}/two-factor/disable:
1519 summary: Disable two factor auth
1520 operationId: disableTwoFactor
1521 description: Disable two factor authentication of a user
1525 - $ref: '#/components/parameters/id'
1534 description: Password of the currently authenticated user
1537 description: successful operation
1539 description: invalid password
1541 description: user not found
1544 /api/v1/users/ask-send-verify-email:
1546 summary: Resend user verification link
1547 operationId: resendEmailToVerifyUser
1553 description: successful operation
1557 summary: Get my user information
1558 operationId: getUserInfo
1566 description: successful operation
1572 $ref: '#/components/schemas/User'
1574 summary: Update my user information
1575 operationId: putUserInfo
1583 description: successful operation
1588 $ref: '#/components/schemas/UpdateMe'
1591 /api/v1/users/me/videos/imports:
1593 summary: Get video imports of my user
1601 - $ref: '#/components/parameters/start'
1602 - $ref: '#/components/parameters/count'
1603 - $ref: '#/components/parameters/sort'
1608 description: Filter on import target URL
1612 name: videoChannelSyncId
1615 description: Filter on imports created by a specific channel synchronization
1622 description: Search in video names
1627 description: successful operation
1631 $ref: '#/components/schemas/VideoImportsList'
1633 /api/v1/users/me/video-quota-used:
1635 summary: Get my user used quota
1643 description: successful operation
1651 description: The user video quota used so far in bytes
1652 example: 16810141515
1653 videoQuotaUsedDaily:
1655 description: The user video quota used today in bytes
1658 '/api/v1/users/me/videos/{videoId}/rating':
1660 summary: Get rate of my user for a video
1670 description: The video id
1672 $ref: '#/components/schemas/Video/properties/id'
1675 description: successful operation
1679 $ref: '#/components/schemas/GetMeVideoRating'
1681 /api/v1/users/me/videos:
1683 summary: Get videos of my user
1691 - $ref: '#/components/parameters/start'
1692 - $ref: '#/components/parameters/count'
1693 - $ref: '#/components/parameters/sort'
1696 description: successful operation
1700 $ref: '#/components/schemas/VideoListResponse'
1702 /api/v1/users/me/subscriptions:
1704 summary: Get my user subscriptions
1711 - $ref: '#/components/parameters/start'
1712 - $ref: '#/components/parameters/count'
1713 - $ref: '#/components/parameters/sort'
1716 description: successful operation
1720 $ref: '#/components/schemas/VideoChannelList'
1724 summary: Add subscription to my user
1737 description: uri of the video channels to subscribe to
1743 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1746 description: successful operation
1748 /api/v1/users/me/subscriptions/exist:
1750 summary: Get if subscriptions exist for my user
1757 - $ref: '#/components/parameters/subscriptionsUris'
1760 description: successful operation
1766 /api/v1/users/me/subscriptions/videos:
1768 summary: List videos of subscriptions of my user
1776 - $ref: '#/components/parameters/categoryOneOf'
1777 - $ref: '#/components/parameters/isLive'
1778 - $ref: '#/components/parameters/tagsOneOf'
1779 - $ref: '#/components/parameters/tagsAllOf'
1780 - $ref: '#/components/parameters/licenceOneOf'
1781 - $ref: '#/components/parameters/languageOneOf'
1782 - $ref: '#/components/parameters/nsfw'
1783 - $ref: '#/components/parameters/isLocal'
1784 - $ref: '#/components/parameters/include'
1785 - $ref: '#/components/parameters/privacyOneOf'
1786 - $ref: '#/components/parameters/hasHLSFiles'
1787 - $ref: '#/components/parameters/hasWebtorrentFiles'
1788 - $ref: '#/components/parameters/skipCount'
1789 - $ref: '#/components/parameters/start'
1790 - $ref: '#/components/parameters/count'
1791 - $ref: '#/components/parameters/videosSort'
1794 description: successful operation
1798 $ref: '#/components/schemas/VideoListResponse'
1800 '/api/v1/users/me/subscriptions/{subscriptionHandle}':
1802 summary: Get subscription of my user
1809 - $ref: '#/components/parameters/subscriptionHandle'
1812 description: successful operation
1816 $ref: '#/components/schemas/VideoChannel'
1818 summary: Delete subscription of my user
1825 - $ref: '#/components/parameters/subscriptionHandle'
1828 description: successful operation
1830 /api/v1/users/me/notifications:
1832 summary: List my notifications
1840 description: only list unread notifications
1843 - $ref: '#/components/parameters/start'
1844 - $ref: '#/components/parameters/count'
1845 - $ref: '#/components/parameters/sort'
1848 description: successful operation
1852 $ref: '#/components/schemas/NotificationListResponse'
1854 /api/v1/users/me/notifications/read:
1856 summary: Mark notifications as read by their id
1869 description: ids of the notifications to mark as read
1876 description: successful operation
1878 /api/v1/users/me/notifications/read-all:
1880 summary: Mark all my notification as read
1887 description: successful operation
1889 /api/v1/users/me/notification-settings:
1891 summary: Update my notification settings
1902 newVideoFromSubscription:
1903 $ref: '#/components/schemas/NotificationSettingValue'
1904 newCommentOnMyVideo:
1905 $ref: '#/components/schemas/NotificationSettingValue'
1907 $ref: '#/components/schemas/NotificationSettingValue'
1908 videoAutoBlacklistAsModerator:
1909 $ref: '#/components/schemas/NotificationSettingValue'
1911 $ref: '#/components/schemas/NotificationSettingValue'
1913 $ref: '#/components/schemas/NotificationSettingValue'
1914 myVideoImportFinished:
1915 $ref: '#/components/schemas/NotificationSettingValue'
1917 $ref: '#/components/schemas/NotificationSettingValue'
1918 newUserRegistration:
1919 $ref: '#/components/schemas/NotificationSettingValue'
1921 $ref: '#/components/schemas/NotificationSettingValue'
1922 newInstanceFollower:
1923 $ref: '#/components/schemas/NotificationSettingValue'
1924 autoInstanceFollowing:
1925 $ref: '#/components/schemas/NotificationSettingValue'
1928 description: successful operation
1930 /api/v1/users/me/history/videos:
1932 summary: List watched videos history
1938 - $ref: '#/components/parameters/start'
1939 - $ref: '#/components/parameters/count'
1940 - $ref: '#/components/parameters/search'
1943 description: successful operation
1947 $ref: '#/components/schemas/VideoListResponse'
1949 /api/v1/users/me/history/videos/{videoId}:
1951 summary: Delete history element
1961 $ref: '#/components/schemas/Video/properties/id'
1964 description: successful operation
1966 /api/v1/users/me/history/videos/remove:
1968 summary: Clear video history
1975 multipart/form-data:
1980 description: history before this date will be deleted
1985 description: successful operation
1987 /api/v1/users/me/avatar/pick:
1989 summary: Update my user avatar
1996 description: successful operation
2005 $ref: '#/components/schemas/ActorImage'
2007 description: image file too large
2009 X-File-Maximum-Size:
2013 description: Maximum file size for the avatar
2016 multipart/form-data:
2021 description: The file to upload
2026 contentType: image/png, image/jpeg
2028 /api/v1/users/me/avatar:
2030 summary: Delete my avatar
2037 description: successful operation
2039 /api/v1/videos/ownership:
2041 summary: List video ownership changes
2043 - Video Ownership Change
2048 description: successful operation
2050 '/api/v1/videos/ownership/{id}/accept':
2052 summary: Accept ownership change request
2054 - Video Ownership Change
2058 - $ref: '#/components/parameters/idOrUUID'
2061 description: successful operation
2063 description: cannot terminate an ownership change of another user
2065 description: video ownership change not found
2067 '/api/v1/videos/ownership/{id}/refuse':
2069 summary: Refuse ownership change request
2071 - Video Ownership Change
2075 - $ref: '#/components/parameters/idOrUUID'
2078 description: successful operation
2080 description: cannot terminate an ownership change of another user
2082 description: video ownership change not found
2084 '/api/v1/videos/{id}/give-ownership':
2086 summary: Request ownership change
2088 - Video Ownership Change
2092 - $ref: '#/components/parameters/idOrUUID'
2096 application/x-www-form-urlencoded:
2106 description: successful operation
2108 description: changing video ownership to a remote account is not supported yet
2110 description: video not found
2112 '/api/v1/videos/{id}/token':
2114 summary: Request video token
2115 operationId: requestVideoToken
2116 description: Request special tokens that expire quickly to use them in some context (like accessing private static files)
2122 - $ref: '#/components/parameters/idOrUUID'
2125 description: successful operation
2129 $ref: '#/components/schemas/VideoTokenResponse'
2131 description: incorrect parameters
2133 description: video not found
2135 /api/v1/videos/{id}/studio/edit:
2137 summary: Create a studio task
2141 description: Create a task to edit a video (cut, add intro/outro etc)
2145 - $ref: '#/components/parameters/idOrUUID'
2149 application/x-www-form-urlencoded:
2151 $ref: '#/components/schemas/VideoStudioCreateTask'
2154 description: successful operation
2156 description: incorrect parameters
2158 description: video not found
2162 summary: List videos
2163 operationId: getVideos
2167 - $ref: '#/components/parameters/categoryOneOf'
2168 - $ref: '#/components/parameters/isLive'
2169 - $ref: '#/components/parameters/tagsOneOf'
2170 - $ref: '#/components/parameters/tagsAllOf'
2171 - $ref: '#/components/parameters/licenceOneOf'
2172 - $ref: '#/components/parameters/languageOneOf'
2173 - $ref: '#/components/parameters/nsfw'
2174 - $ref: '#/components/parameters/isLocal'
2175 - $ref: '#/components/parameters/include'
2176 - $ref: '#/components/parameters/privacyOneOf'
2177 - $ref: '#/components/parameters/hasHLSFiles'
2178 - $ref: '#/components/parameters/hasWebtorrentFiles'
2179 - $ref: '#/components/parameters/skipCount'
2180 - $ref: '#/components/parameters/start'
2181 - $ref: '#/components/parameters/count'
2182 - $ref: '#/components/parameters/videosSort'
2185 description: successful operation
2189 $ref: '#/components/schemas/VideoListResponse'
2191 /api/v1/videos/categories:
2193 summary: List available video categories
2194 operationId: getCategories
2199 description: successful operation
2208 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
2210 /api/v1/videos/licences:
2212 summary: List available video licences
2213 operationId: getLicences
2218 description: successful operation
2227 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
2229 /api/v1/videos/languages:
2231 summary: List available video languages
2232 operationId: getLanguages
2237 description: successful operation
2246 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
2248 /api/v1/videos/privacies:
2250 summary: List available video privacy policies
2251 operationId: getPrivacyPolicies
2256 description: successful operation
2265 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
2267 '/api/v1/videos/{id}':
2269 summary: Update a video
2270 operationId: putVideo
2276 - $ref: '#/components/parameters/idOrUUID'
2279 description: successful operation
2282 multipart/form-data:
2287 description: Video thumbnail file
2291 description: Video preview file
2295 $ref: '#/components/schemas/VideoCategorySet'
2297 $ref: '#/components/schemas/VideoLicenceSet'
2299 $ref: '#/components/schemas/VideoLanguageSet'
2301 $ref: '#/components/schemas/VideoPrivacySet'
2303 description: Video description
2306 description: Whether or not we wait transcoding before publish the video
2309 description: A text tell the audience how to support the video creator
2310 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2313 description: Whether or not this video contains sensitive content
2316 description: Video name
2321 description: Video tags (maximum 5 tags each between 2 and 30 characters)
2330 description: Enable or disable comments for this video
2333 description: Enable or disable downloading for this video
2335 originallyPublishedAt:
2336 description: Date when the content was originally published
2340 $ref: '#/components/schemas/VideoScheduledUpdate'
2343 contentType: image/jpeg
2345 contentType: image/jpeg
2347 summary: Get a video
2348 operationId: getVideo
2352 - $ref: '#/components/parameters/idOrUUID'
2355 description: successful operation
2359 $ref: '#/components/schemas/VideoDetails'
2361 summary: Delete a video
2362 operationId: delVideo
2368 - $ref: '#/components/parameters/idOrUUID'
2371 description: successful operation
2373 '/api/v1/videos/{id}/description':
2375 summary: Get complete video description
2376 operationId: getVideoDesc
2380 - $ref: '#/components/parameters/idOrUUID'
2383 description: successful operation
2392 **[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)**
2394 '/api/v1/videos/{id}/source':
2396 summary: Get video source file metadata
2397 operationId: getVideoSource
2401 - $ref: '#/components/parameters/idOrUUID'
2404 description: successful operation
2408 $ref: '#/components/schemas/VideoSource'
2410 '/api/v1/videos/{id}/views':
2412 summary: Notify user is watching a video
2413 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.
2414 operationId: addView
2418 - $ref: '#/components/parameters/idOrUUID'
2423 $ref: '#/components/schemas/UserViewingVideo'
2427 description: successful operation
2429 '/api/v1/videos/{id}/watching':
2431 summary: Set watching progress of a video
2433 description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
2439 - $ref: '#/components/parameters/idOrUUID'
2444 $ref: '#/components/schemas/UserViewingVideo'
2448 description: successful operation
2450 '/api/v1/videos/{id}/stats/overall':
2452 summary: Get overall stats of a video
2458 - $ref: '#/components/parameters/idOrUUID'
2461 description: Filter stats by start date
2467 description: Filter stats by end date
2473 description: successful operation
2477 $ref: '#/components/schemas/VideoStatsOverall'
2479 '/api/v1/videos/{id}/stats/retention':
2481 summary: Get retention stats of a video
2487 - $ref: '#/components/parameters/idOrUUID'
2490 description: successful operation
2494 $ref: '#/components/schemas/VideoStatsRetention'
2496 '/api/v1/videos/{id}/stats/timeseries/{metric}':
2498 summary: Get timeserie stats of a video
2504 - $ref: '#/components/parameters/idOrUUID'
2509 description: The metric to get
2514 - 'aggregateWatchTime'
2517 description: Filter stats by start date
2523 description: Filter stats by end date
2529 description: successful operation
2533 $ref: '#/components/schemas/VideoStatsTimeserie'
2535 /api/v1/videos/upload:
2537 summary: Upload a video
2538 description: Uses a single request to upload a video.
2539 operationId: uploadLegacy
2547 description: successful operation
2551 $ref: '#/components/schemas/VideoUploadResponse'
2553 description: video didn't pass upload filter
2555 description: upload has timed out
2557 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
2559 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
2560 - `quota_reached` for quota limits whether daily or global
2562 X-File-Maximum-Size:
2566 description: Maximum file size for the video
2568 description: video type unsupported
2570 description: video unreadable
2573 multipart/form-data:
2575 $ref: '#/components/schemas/VideoUploadRequestLegacy'
2578 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
2580 contentType: image/jpeg
2582 contentType: image/jpeg
2587 USERNAME="<your_username>"
2588 PASSWORD="<your_password>"
2589 FILE_PATH="<your_file_path>"
2590 CHANNEL_ID="<your_channel_id>"
2592 API="https://peertube2.cpy.re/api/v1"
2595 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
2596 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
2597 token=$(curl -s "$API/users/token" \
2598 --data client_id="$client_id" \
2599 --data client_secret="$client_secret" \
2600 --data grant_type=password \
2601 --data username="$USERNAME" \
2602 --data password="$PASSWORD" \
2603 | jq -r ".access_token")
2606 curl -s "$API/videos/upload" \
2607 -H "Authorization: Bearer $token" \
2609 --form videofile=@"$FILE_PATH" \
2610 --form channelId=$CHANNEL_ID \
2613 /api/v1/videos/upload-resumable:
2615 summary: Initialize the resumable upload of a video
2616 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
2617 operationId: uploadResumableInit
2624 - name: X-Upload-Content-Length
2630 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2631 - name: X-Upload-Content-Type
2638 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2643 $ref: '#/components/schemas/VideoUploadRequestResumable'
2646 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2648 description: created
2654 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2660 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2662 Disambiguate via `type`:
2663 - `max_file_size_reached` for the absolute file size limit
2664 - `quota_reached` for quota limits whether daily or global
2666 description: video type unsupported
2668 summary: Send chunk for the resumable upload of a video
2669 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
2670 operationId: uploadResumable
2681 Created session id to proceed with. If you didn't send chunks in the last hour, it is
2682 not valid anymore and you need to initialize a new upload.
2685 - name: Content-Range
2689 example: bytes 0-262143/2469036
2692 Specifies the bytes in the file that the request is uploading.
2694 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2695 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2696 - name: Content-Length
2703 Size of the chunk that the request is sending.
2705 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2706 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2709 application/octet-stream:
2715 description: last chunk received
2723 $ref: '#/components/schemas/VideoUploadResponse'
2725 description: resume incomplete
2730 example: bytes=0-262143
2736 description: video didn't pass upload filter
2738 description: upload not found
2740 description: chunk doesn't match range
2742 description: video unreadable
2744 description: too many concurrent requests
2746 description: upload is already being processed
2753 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2754 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2755 operationId: uploadResumableCancel
2766 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2767 not valid anymore and the upload session has already been deleted with its data ;-)
2770 - name: Content-Length
2778 description: upload cancelled
2785 description: upload not found
2787 /api/v1/videos/imports:
2789 summary: Import a video
2790 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2791 operationId: importVideo
2799 multipart/form-data:
2801 $ref: '#/components/schemas/VideoCreateImport'
2804 contentType: application/x-bittorrent
2806 contentType: image/jpeg
2808 contentType: image/jpeg
2811 description: successful operation
2815 $ref: '#/components/schemas/VideoUploadResponse'
2817 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2819 description: video didn't pass pre-import filter
2821 description: HTTP or Torrent/magnetURI import not enabled
2823 /api/v1/videos/imports/{id}/cancel:
2825 summary: Cancel video import
2826 description: Cancel a pending video import
2832 - $ref: '#/components/parameters/id'
2835 description: successful operation
2837 /api/v1/videos/imports/{id}:
2839 summary: Delete video import
2840 description: Delete ended video import
2846 - $ref: '#/components/parameters/id'
2849 description: successful operation
2851 /api/v1/videos/live:
2853 summary: Create a live
2854 operationId: addLive
2862 description: successful operation
2866 $ref: '#/components/schemas/VideoUploadResponse'
2868 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2870 Disambiguate via `type`:
2871 - default type for a validation error
2872 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2874 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2876 Disambiguate via `type`:
2877 - `live_not_enabled` for a disabled live feature
2878 - `live_not_allowing_replay` for a disabled replay feature
2879 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2880 - `max_user_lives_limit_reached` for the user concurrent live limit
2883 multipart/form-data:
2888 description: Channel id that will contain this live video
2893 description: User can stream multiple times in a permanent live
2896 description: User can select live latency mode if enabled by the instance
2897 $ref: '#/components/schemas/LiveVideoLatencyMode'
2899 description: Live video/replay thumbnail file
2903 description: Live video/replay preview file
2907 $ref: '#/components/schemas/VideoPrivacySet'
2909 $ref: '#/components/schemas/VideoCategorySet'
2911 $ref: '#/components/schemas/VideoLicenceSet'
2913 $ref: '#/components/schemas/VideoLanguageSet'
2915 description: Live video/replay description
2918 description: A text tell the audience how to support the creator
2919 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2922 description: Whether or not this live video/replay contains sensitive content
2925 description: Live video/replay name
2930 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2939 description: Enable or disable comments for this live video/replay
2942 description: Enable or disable downloading for the replay of this live video
2949 contentType: image/jpeg
2951 contentType: image/jpeg
2953 /api/v1/videos/live/{id}:
2955 summary: Get information about a live
2956 operationId: getLiveId
2963 - $ref: '#/components/parameters/idOrUUID'
2966 description: successful operation
2970 $ref: '#/components/schemas/LiveVideoResponse'
2972 summary: Update information about a live
2973 operationId: updateLiveId
2980 - $ref: '#/components/parameters/idOrUUID'
2985 $ref: '#/components/schemas/LiveVideoUpdate'
2988 description: successful operation
2990 description: bad parameters or trying to update a live that has already started
2992 description: trying to save replay of the live but saving replay is not enabled on the instance
2993 /api/v1/videos/live/{id}/sessions:
2995 summary: List live sessions
2996 description: List all sessions created in a particular live
3002 - $ref: '#/components/parameters/idOrUUID'
3005 description: successful operation
3017 $ref: '#/components/schemas/LiveVideoSessionResponse'
3018 /api/v1/videos/{id}/live-session:
3020 summary: Get live session of a replay
3021 description: If the video is a replay of a live, you can find the associated live session using this endpoint
3027 - $ref: '#/components/parameters/idOrUUID'
3030 description: successful operation
3034 $ref: '#/components/schemas/LiveVideoSessionResponse'
3036 /api/v1/users/me/abuses:
3038 summary: List my abuses
3039 operationId: getMyAbuses
3048 description: only list the report with this id
3054 $ref: '#/components/schemas/AbuseStateSet'
3055 - $ref: '#/components/parameters/abusesSort'
3056 - $ref: '#/components/parameters/start'
3057 - $ref: '#/components/parameters/count'
3060 description: successful operation
3072 $ref: '#/components/schemas/Abuse'
3076 summary: List abuses
3077 operationId: getAbuses
3087 description: only list the report with this id
3090 - name: predefinedReason
3092 description: predefined reason the listed reports should contain
3094 $ref: '#/components/schemas/PredefinedAbuseReasons'
3097 description: plain search that will match with video titles, reporter names and more
3103 $ref: '#/components/schemas/AbuseStateSet'
3104 - name: searchReporter
3106 description: only list reports of a specific reporter
3109 - name: searchReportee
3110 description: only list reports of a specific reportee
3116 description: only list reports of a specific video
3119 - name: searchVideoChannel
3121 description: only list reports of a specific video channel
3126 description: only list deleted or blocklisted videos
3134 description: only list account, comment or video reports
3141 - $ref: '#/components/parameters/start'
3142 - $ref: '#/components/parameters/count'
3143 - $ref: '#/components/parameters/abusesSort'
3146 description: successful operation
3158 $ref: '#/components/schemas/Abuse'
3160 summary: Report an abuse
3173 description: Reason why the user reports this video
3178 $ref: '#/components/schemas/PredefinedAbuseReasons'
3183 description: Video id to report
3185 - $ref: '#/components/schemas/Video/properties/id'
3189 description: Timestamp in the video that marks the beginning of the report
3194 description: Timestamp in the video that marks the ending of the report
3200 description: Comment id to report
3202 - $ref: '#/components/schemas/VideoComment/properties/id'
3207 description: Account id to report
3213 description: successful operation
3223 $ref: '#/components/schemas/id'
3225 description: incorrect request parameters
3227 '/api/v1/abuses/{abuseId}':
3229 summary: Update an abuse
3237 - $ref: '#/components/parameters/abuseId'
3245 $ref: '#/components/schemas/AbuseStateSet'
3248 description: Update the report comment visible only to the moderation team
3253 description: successful operation
3255 description: abuse not found
3259 summary: Delete an abuse
3265 - $ref: '#/components/parameters/abuseId'
3268 description: successful operation
3270 description: block not found
3272 '/api/v1/abuses/{abuseId}/messages':
3274 summary: List messages of an abuse
3280 - $ref: '#/components/parameters/abuseId'
3283 description: successful operation
3295 $ref: '#/components/schemas/AbuseMessage'
3297 summary: Add message to an abuse
3303 - $ref: '#/components/parameters/abuseId'
3312 description: Message to send
3320 description: successful operation
3322 description: incorrect request parameters
3324 '/api/v1/abuses/{abuseId}/messages/{abuseMessageId}':
3326 summary: Delete an abuse message
3332 - $ref: '#/components/parameters/abuseId'
3333 - $ref: '#/components/parameters/abuseMessageId'
3336 description: successful operation
3338 '/api/v1/videos/{id}/blacklist':
3340 summary: Block a video
3341 operationId: addVideoBlock
3349 - $ref: '#/components/parameters/idOrUUID'
3352 description: successful operation
3354 summary: Unblock a video by its id
3355 operationId: delVideoBlock
3363 - $ref: '#/components/parameters/idOrUUID'
3366 description: successful operation
3368 description: block not found
3370 /api/v1/videos/blacklist:
3374 summary: List video blocks
3375 operationId: getVideoBlocks
3384 list only blocks that match this type:
3388 - `2`: automatic block that needs review
3396 description: plain search that will match with video titles, and more
3399 - $ref: '#/components/parameters/start'
3400 - $ref: '#/components/parameters/count'
3401 - $ref: '#/components/parameters/blacklistsSort'
3404 description: successful operation
3416 $ref: '#/components/schemas/VideoBlacklist'
3418 /api/v1/videos/{id}/captions:
3420 summary: List captions of a video
3421 operationId: getVideoCaptions
3425 - $ref: '#/components/parameters/idOrUUID'
3428 description: successful operation
3440 $ref: '#/components/schemas/VideoCaption'
3442 /api/v1/videos/{id}/captions/{captionLanguage}:
3444 summary: Add or replace a video caption
3445 operationId: addVideoCaption
3452 - $ref: '#/components/parameters/idOrUUID'
3453 - $ref: '#/components/parameters/captionLanguage'
3456 multipart/form-data:
3461 description: The file to upload.
3466 contentType: text/vtt, application/x-subrip, text/plain
3469 description: successful operation
3471 description: video or language not found
3473 summary: Delete a video caption
3474 operationId: delVideoCaption
3481 - $ref: '#/components/parameters/idOrUUID'
3482 - $ref: '#/components/parameters/captionLanguage'
3485 description: successful operation
3487 description: video or language or caption for that language not found
3489 /api/v1/video-channels:
3491 summary: List video channels
3492 operationId: getVideoChannels
3496 - $ref: '#/components/parameters/start'
3497 - $ref: '#/components/parameters/count'
3498 - $ref: '#/components/parameters/sort'
3501 description: successful operation
3505 $ref: '#/components/schemas/VideoChannelList'
3507 summary: Create a video channel
3508 operationId: addVideoChannel
3515 description: successful operation
3525 $ref: '#/components/schemas/id'
3530 $ref: '#/components/schemas/VideoChannelCreate'
3532 '/api/v1/video-channels/{channelHandle}':
3534 summary: Get a video channel
3535 operationId: getVideoChannel
3539 - $ref: '#/components/parameters/channelHandle'
3542 description: successful operation
3546 $ref: '#/components/schemas/VideoChannel'
3548 summary: Update a video channel
3549 operationId: putVideoChannel
3555 - $ref: '#/components/parameters/channelHandle'
3558 description: successful operation
3563 $ref: '#/components/schemas/VideoChannelUpdate'
3565 summary: Delete a video channel
3566 operationId: delVideoChannel
3572 - $ref: '#/components/parameters/channelHandle'
3575 description: successful operation
3577 '/api/v1/video-channels/{channelHandle}/videos':
3579 summary: List videos of a video channel
3580 operationId: getVideoChannelVideos
3585 - $ref: '#/components/parameters/channelHandle'
3586 - $ref: '#/components/parameters/categoryOneOf'
3587 - $ref: '#/components/parameters/isLive'
3588 - $ref: '#/components/parameters/tagsOneOf'
3589 - $ref: '#/components/parameters/tagsAllOf'
3590 - $ref: '#/components/parameters/licenceOneOf'
3591 - $ref: '#/components/parameters/languageOneOf'
3592 - $ref: '#/components/parameters/nsfw'
3593 - $ref: '#/components/parameters/isLocal'
3594 - $ref: '#/components/parameters/include'
3595 - $ref: '#/components/parameters/privacyOneOf'
3596 - $ref: '#/components/parameters/hasHLSFiles'
3597 - $ref: '#/components/parameters/hasWebtorrentFiles'
3598 - $ref: '#/components/parameters/skipCount'
3599 - $ref: '#/components/parameters/start'
3600 - $ref: '#/components/parameters/count'
3601 - $ref: '#/components/parameters/videosSort'
3604 description: successful operation
3608 $ref: '#/components/schemas/VideoListResponse'
3610 '/api/v1/video-channels/{channelHandle}/followers':
3614 summary: 'List followers of a video channel'
3617 operationId: getVideoChannelFollowers
3619 - $ref: '#/components/parameters/channelHandle'
3620 - $ref: '#/components/parameters/start'
3621 - $ref: '#/components/parameters/count'
3622 - $ref: '#/components/parameters/followersSort'
3623 - $ref: '#/components/parameters/search'
3626 description: successful operation
3638 $ref: '#/components/schemas/Follow'
3640 '/api/v1/video-channels/{channelHandle}/avatar/pick':
3642 summary: Update channel avatar
3648 - $ref: '#/components/parameters/channelHandle'
3651 description: successful operation
3660 $ref: '#/components/schemas/ActorImage'
3662 description: image file too large
3664 X-File-Maximum-Size:
3668 description: Maximum file size for the avatar
3671 multipart/form-data:
3676 description: The file to upload.
3681 contentType: image/png, image/jpeg
3683 '/api/v1/video-channels/{channelHandle}/avatar':
3685 summary: Delete channel avatar
3691 - $ref: '#/components/parameters/channelHandle'
3694 description: successful operation
3696 '/api/v1/video-channels/{channelHandle}/banner/pick':
3698 summary: Update channel banner
3704 - $ref: '#/components/parameters/channelHandle'
3707 description: successful operation
3716 $ref: '#/components/schemas/ActorImage'
3718 description: image file too large
3720 X-File-Maximum-Size:
3724 description: Maximum file size for the banner
3727 multipart/form-data:
3732 description: The file to upload.
3737 contentType: image/png, image/jpeg
3739 '/api/v1/video-channels/{channelHandle}/banner':
3741 summary: Delete channel banner
3747 - $ref: '#/components/parameters/channelHandle'
3750 description: successful operation
3752 '/api/v1/video-channels/{channelHandle}/import-videos':
3754 summary: Import videos in channel
3755 description: Import a remote channel/playlist videos into a channel
3762 - $ref: '#/components/parameters/channelHandle'
3767 $ref: '#/components/schemas/ImportVideosInChannelCreate'
3770 description: successful operation
3772 '/api/v1/video-channel-syncs':
3774 summary: Create a synchronization for a video channel
3775 operationId: addVideoChannelSync
3784 $ref: '#/components/schemas/VideoChannelSyncCreate'
3787 description: successful operation
3794 $ref: "#/components/schemas/VideoChannelSync"
3796 '/api/v1/video-channel-syncs/{channelSyncId}':
3798 summary: Delete a video channel synchronization
3799 operationId: delVideoChannelSync
3805 - $ref: '#/components/parameters/channelSyncId'
3808 description: successful operation
3810 '/api/v1/video-channel-syncs/{channelSyncId}/sync':
3812 summary: Triggers the channel synchronization job, fetching all the videos from the remote channel
3813 operationId: triggerVideoChannelSync
3819 - $ref: '#/components/parameters/channelSyncId'
3822 description: successful operation
3825 /api/v1/video-playlists/privacies:
3827 summary: List available playlist privacy policies
3828 operationId: getPlaylistPrivacyPolicies
3833 description: successful operation
3842 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3844 /api/v1/video-playlists:
3846 summary: List video playlists
3847 operationId: getPlaylists
3851 - $ref: '#/components/parameters/start'
3852 - $ref: '#/components/parameters/count'
3853 - $ref: '#/components/parameters/sort'
3856 description: successful operation
3868 $ref: '#/components/schemas/VideoPlaylist'
3870 summary: Create a video playlist
3871 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3872 operationId: addPlaylist
3879 description: successful operation
3889 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3891 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3893 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3896 multipart/form-data:
3901 description: Video playlist display name
3906 description: Video playlist thumbnail file
3910 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3912 description: Video playlist description
3918 - $ref: '#/components/schemas/id'
3919 description: Video channel in which the playlist will be published
3924 contentType: image/jpeg
3926 /api/v1/video-playlists/{playlistId}:
3928 summary: Get a video playlist
3932 - $ref: '#/components/parameters/playlistId'
3935 description: successful operation
3939 $ref: '#/components/schemas/VideoPlaylist'
3941 summary: Update a video playlist
3942 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3949 description: successful operation
3951 - $ref: '#/components/parameters/playlistId'
3954 multipart/form-data:
3959 description: Video playlist display name
3964 description: Video playlist thumbnail file
3968 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3970 description: Video playlist description
3974 - $ref: '#/components/schemas/id'
3975 description: Video channel in which the playlist will be published
3978 contentType: image/jpeg
3980 summary: Delete a video playlist
3986 - $ref: '#/components/parameters/playlistId'
3989 description: successful operation
3991 /api/v1/video-playlists/{playlistId}/videos:
3993 summary: 'List videos of a playlist'
3994 operationId: getVideoPlaylistVideos
3999 - $ref: '#/components/parameters/playlistId'
4000 - $ref: '#/components/parameters/start'
4001 - $ref: '#/components/parameters/count'
4004 description: successful operation
4008 $ref: '#/components/schemas/VideoListResponse'
4010 summary: Add a video in a playlist
4011 operationId: addVideoPlaylistVideo
4018 - $ref: '#/components/parameters/playlistId'
4021 description: successful operation
4027 videoPlaylistElement:
4041 - $ref: '#/components/schemas/Video/properties/uuid'
4042 - $ref: '#/components/schemas/Video/properties/id'
4043 description: Video to add in the playlist
4047 description: Start the video at this specific timestamp
4051 description: Stop the video at this specific timestamp
4055 /api/v1/video-playlists/{playlistId}/videos/reorder:
4057 summary: 'Reorder a playlist'
4058 operationId: reorderVideoPlaylist
4064 - $ref: '#/components/parameters/playlistId'
4067 description: successful operation
4076 description: 'Start position of the element to reorder'
4078 insertAfterPosition:
4080 description: 'New position for the block to reorder, to add the block before the first element'
4084 description: 'How many element from `startPosition` to reorder'
4088 - insertAfterPosition
4090 /api/v1/video-playlists/{playlistId}/videos/{playlistElementId}:
4092 summary: Update a playlist element
4093 operationId: putVideoPlaylistVideo
4099 - $ref: '#/components/parameters/playlistId'
4100 - $ref: '#/components/parameters/playlistElementId'
4103 description: successful operation
4113 description: Start the video at this specific timestamp
4117 description: Stop the video at this specific timestamp
4119 summary: Delete an element from a playlist
4120 operationId: delVideoPlaylistVideo
4126 - $ref: '#/components/parameters/playlistId'
4127 - $ref: '#/components/parameters/playlistElementId'
4130 description: successful operation
4132 '/api/v1/users/me/video-playlists/videos-exist':
4134 summary: Check video exists in my playlists
4143 description: The video ids to check
4147 $ref: '#/components/schemas/Video/properties/id'
4150 description: successful operation
4172 '/api/v1/accounts/{name}/video-channels':
4174 summary: List video channels of an account
4179 - $ref: '#/components/parameters/name'
4182 description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
4185 - $ref: '#/components/parameters/start'
4186 - $ref: '#/components/parameters/count'
4187 - $ref: '#/components/parameters/sort'
4190 description: successful operation
4194 $ref: '#/components/schemas/VideoChannelList'
4196 '/api/v1/accounts/{name}/video-channel-syncs':
4198 summary: List the synchronizations of video channels of an account
4204 - $ref: '#/components/parameters/name'
4205 - $ref: '#/components/parameters/start'
4206 - $ref: '#/components/parameters/count'
4207 - $ref: '#/components/parameters/sort'
4210 description: successful operation
4214 $ref: '#/components/schemas/VideoChannelSyncList'
4216 '/api/v1/accounts/{name}/ratings':
4218 summary: List ratings of an account
4224 - $ref: '#/components/parameters/name'
4225 - $ref: '#/components/parameters/start'
4226 - $ref: '#/components/parameters/count'
4227 - $ref: '#/components/parameters/sort'
4231 description: Optionally filter which ratings to retrieve
4239 description: successful operation
4245 $ref: '#/components/schemas/VideoRating'
4247 '/api/v1/videos/{id}/comment-threads':
4249 summary: List threads of a video
4253 - $ref: '#/components/parameters/idOrUUID'
4254 - $ref: '#/components/parameters/start'
4255 - $ref: '#/components/parameters/count'
4256 - $ref: '#/components/parameters/commentsSort'
4259 description: successful operation
4263 $ref: '#/components/schemas/CommentThreadResponse'
4265 summary: Create a thread
4271 - $ref: '#/components/parameters/idOrUUID'
4274 description: successful operation
4278 $ref: '#/components/schemas/CommentThreadPostResponse'
4280 description: video does not exist
4289 - $ref: '#/components/schemas/VideoComment/properties/text'
4295 '/api/v1/videos/{id}/comment-threads/{threadId}':
4297 summary: Get a thread
4301 - $ref: '#/components/parameters/idOrUUID'
4302 - $ref: '#/components/parameters/threadId'
4305 description: successful operation
4309 $ref: '#/components/schemas/VideoCommentThreadTree'
4311 '/api/v1/videos/{id}/comments/{commentId}':
4313 summary: Reply to a thread of a video
4319 - $ref: '#/components/parameters/idOrUUID'
4320 - $ref: '#/components/parameters/commentId'
4323 description: successful operation
4327 $ref: '#/components/schemas/CommentThreadPostResponse'
4329 description: thread or video does not exist
4338 - $ref: '#/components/schemas/VideoComment/properties/text'
4344 summary: Delete a comment or a reply
4350 - $ref: '#/components/parameters/idOrUUID'
4351 - $ref: '#/components/parameters/commentId'
4354 description: successful operation
4356 description: cannot remove comment of another user
4358 description: comment or video does not exist
4360 description: comment is already deleted
4362 '/api/v1/videos/{id}/rate':
4364 summary: Like/dislike a video
4370 - $ref: '#/components/parameters/idOrUUID'
4386 description: successful operation
4388 description: video does not exist
4390 '/api/v1/videos/{id}/hls':
4392 summary: Delete video HLS files
4398 operationId: delVideoHLS
4400 - $ref: '#/components/parameters/idOrUUID'
4403 description: successful operation
4405 description: video does not exist
4406 '/api/v1/videos/{id}/webtorrent':
4408 summary: Delete video WebTorrent files
4414 operationId: delVideoWebTorrent
4416 - $ref: '#/components/parameters/idOrUUID'
4419 description: successful operation
4421 description: video does not exist
4423 '/api/v1/videos/{id}/transcoding':
4425 summary: Create a transcoding job
4431 operationId: createVideoTranscoding
4433 - $ref: '#/components/parameters/idOrUUID'
4449 description: successful operation
4451 description: video does not exist
4453 /api/v1/search/videos:
4457 summary: Search videos
4458 operationId: searchVideos
4463 allowEmptyValue: false
4465 String to search. If the user can make a remote URI search, and the string is an URI then the
4466 PeerTube instance will fetch the remote object and add it to its database. Then,
4467 you can use the REST API to fetch the complete video information and interact with it.
4470 - $ref: '#/components/parameters/categoryOneOf'
4471 - $ref: '#/components/parameters/isLive'
4472 - $ref: '#/components/parameters/tagsOneOf'
4473 - $ref: '#/components/parameters/tagsAllOf'
4474 - $ref: '#/components/parameters/licenceOneOf'
4475 - $ref: '#/components/parameters/languageOneOf'
4476 - $ref: '#/components/parameters/nsfw'
4477 - $ref: '#/components/parameters/isLocal'
4478 - $ref: '#/components/parameters/include'
4479 - $ref: '#/components/parameters/privacyOneOf'
4480 - $ref: '#/components/parameters/hasHLSFiles'
4481 - $ref: '#/components/parameters/hasWebtorrentFiles'
4482 - $ref: '#/components/parameters/skipCount'
4483 - $ref: '#/components/parameters/start'
4484 - $ref: '#/components/parameters/count'
4485 - $ref: '#/components/parameters/searchTarget'
4486 - $ref: '#/components/parameters/videosSearchSort'
4489 description: Get videos that are published after this date
4495 description: Get videos that are published before this date
4499 - name: originallyPublishedStartDate
4501 description: Get videos that are originally published after this date
4505 - name: originallyPublishedEndDate
4507 description: Get videos that are originally published before this date
4513 description: Get videos that have this minimum duration
4518 description: Get videos that have this maximum duration
4522 'searchTarget === search-index':
4523 $ref: '#/components/callbacks/searchIndex'
4526 description: successful operation
4530 $ref: '#/components/schemas/VideoListResponse'
4532 description: search index unavailable
4534 /api/v1/search/video-channels:
4538 summary: Search channels
4539 operationId: searchChannels
4545 String to search. If the user can make a remote URI search, and the string is an URI then the
4546 PeerTube instance will fetch the remote object and add it to its database. Then,
4547 you can use the REST API to fetch the complete channel information and interact with it.
4550 - $ref: '#/components/parameters/start'
4551 - $ref: '#/components/parameters/count'
4552 - $ref: '#/components/parameters/searchTarget'
4553 - $ref: '#/components/parameters/sort'
4555 'searchTarget === search-index':
4556 $ref: '#/components/callbacks/searchIndex'
4559 description: successful operation
4563 $ref: '#/components/schemas/VideoChannelList'
4565 description: search index unavailable
4567 /api/v1/search/video-playlists:
4571 summary: Search playlists
4572 operationId: searchPlaylists
4578 String to search. If the user can make a remote URI search, and the string is an URI then the
4579 PeerTube instance will fetch the remote object and add it to its database. Then,
4580 you can use the REST API to fetch the complete playlist information and interact with it.
4583 - $ref: '#/components/parameters/start'
4584 - $ref: '#/components/parameters/count'
4585 - $ref: '#/components/parameters/searchTarget'
4586 - $ref: '#/components/parameters/sort'
4588 'searchTarget === search-index':
4589 $ref: '#/components/callbacks/searchIndex'
4592 description: successful operation
4604 $ref: '#/components/schemas/VideoPlaylist'
4606 description: search index unavailable
4608 /api/v1/blocklist/status:
4613 summary: Get block status of accounts/hosts
4618 description: 'Check if these accounts are blocked'
4619 example: [ 'goofy@example.com', 'donald@example.com' ]
4627 description: 'Check if these hosts are blocked'
4628 example: [ 'example.com' ]
4635 description: successful operation
4639 $ref: '#/components/schemas/BlockStatus'
4641 /api/v1/server/blocklist/accounts:
4645 summary: List account blocks
4650 - $ref: '#/components/parameters/start'
4651 - $ref: '#/components/parameters/count'
4652 - $ref: '#/components/parameters/sort'
4655 description: successful operation
4659 summary: Block an account
4671 example: chocobozzz@example.org
4672 description: account to block, in the form `username@domain`
4677 description: successful operation
4679 description: self-blocking forbidden
4681 '/api/v1/server/blocklist/accounts/{accountName}':
4685 summary: Unblock an account by its handle
4693 description: account to unblock, in the form `username@domain`
4698 description: successful operation
4700 description: account or account block does not exist
4702 /api/v1/server/blocklist/servers:
4706 summary: List server blocks
4711 - $ref: '#/components/parameters/start'
4712 - $ref: '#/components/parameters/count'
4713 - $ref: '#/components/parameters/sort'
4716 description: successful operation
4720 summary: Block a server
4733 description: server domain to block
4738 description: successful operation
4740 description: self-blocking forbidden
4742 '/api/v1/server/blocklist/servers/{host}':
4746 summary: Unblock a server by its domain
4754 description: server domain to unblock
4760 description: successful operation
4762 description: account block does not exist
4764 /api/v1/server/redundancy/{host}:
4767 - Instance Redundancy
4768 summary: Update a server redundancy policy
4776 description: server domain to mirror
4788 description: allow mirroring of the host's local videos
4793 description: successful operation
4795 description: server is not already known
4797 /api/v1/server/redundancy/videos:
4801 summary: List videos being mirrored
4802 operationId: getMirroredVideos
4810 description: direction of the mirror
4816 - $ref: '#/components/parameters/start'
4817 - $ref: '#/components/parameters/count'
4818 - $ref: '#/components/parameters/videoRedundanciesSort'
4821 description: successful operation
4827 $ref: '#/components/schemas/VideoRedundancy'
4831 summary: Mirror a video
4832 operationId: putMirroredVideo
4843 $ref: '#/components/schemas/Video/properties/id'
4848 description: successful operation
4850 description: cannot mirror a local video
4852 description: video does not exist
4854 description: video is already mirrored
4856 /api/v1/server/redundancy/videos/{redundancyId}:
4860 summary: Delete a mirror done on a video
4861 operationId: delMirroredVideo
4866 - name: redundancyId
4869 description: id of an existing redundancy on a video
4874 description: successful operation
4876 description: video redundancy not found
4878 /api/v1/server/stats:
4882 summary: Get instance stats
4883 description: Get instance public statistics. This endpoint is cached.
4884 operationId: getInstanceStats
4887 description: successful operation
4891 $ref: '#/components/schemas/ServerStats'
4893 /api/v1/server/logs/client:
4897 summary: Send client log
4898 operationId: sendClientLog
4903 $ref: '#/components/schemas/SendClientLog'
4906 description: successful operation
4908 /api/v1/server/logs:
4912 summary: Get instance logs
4913 operationId: getInstanceLogs
4919 description: successful operation
4927 /api/v1/server/audit-logs:
4931 summary: Get instance audit logs
4932 operationId: getInstanceAuditLogs
4938 description: successful operation
4950 summary: List plugins
4951 operationId: getPlugins
4964 - $ref: '#/components/parameters/start'
4965 - $ref: '#/components/parameters/count'
4966 - $ref: '#/components/parameters/sort'
4969 description: successful operation
4973 $ref: '#/components/schemas/PluginResponse'
4975 /api/v1/plugins/available:
4979 summary: List available plugins
4980 operationId: getAvailablePlugins
4993 - name: currentPeerTubeEngine
4997 - $ref: '#/components/parameters/start'
4998 - $ref: '#/components/parameters/count'
4999 - $ref: '#/components/parameters/sort'
5002 description: successful operation
5006 $ref: '#/components/schemas/PluginResponse'
5008 description: plugin index unavailable
5010 /api/v1/plugins/install:
5014 summary: Install a plugin
5015 operationId: addPlugin
5028 example: peertube-plugin-auth-ldap
5031 additionalProperties: false
5038 additionalProperties: false
5041 description: successful operation
5043 description: should have either `npmName` or `path` set
5045 /api/v1/plugins/update:
5049 summary: Update a plugin
5050 operationId: updatePlugin
5063 example: peertube-plugin-auth-ldap
5066 additionalProperties: false
5073 additionalProperties: false
5076 description: successful operation
5078 description: should have either `npmName` or `path` set
5080 description: existing plugin not found
5082 /api/v1/plugins/uninstall:
5086 summary: Uninstall a plugin
5087 operationId: uninstallPlugin
5099 description: name of the plugin/theme in its package.json
5100 example: peertube-plugin-auth-ldap
5105 description: successful operation
5107 description: existing plugin not found
5109 /api/v1/plugins/{npmName}:
5113 summary: Get a plugin
5114 operationId: getPlugin
5119 - $ref: '#/components/parameters/npmName'
5122 description: successful operation
5126 $ref: '#/components/schemas/Plugin'
5128 description: plugin not found
5130 /api/v1/plugins/{npmName}/settings:
5134 summary: Set a plugin's settings
5139 - $ref: '#/components/parameters/npmName'
5148 additionalProperties: true
5151 description: successful operation
5153 description: plugin not found
5155 /api/v1/plugins/{npmName}/public-settings:
5159 summary: Get a plugin's public settings
5161 - $ref: '#/components/parameters/npmName'
5164 description: successful operation
5169 additionalProperties: true
5171 description: plugin not found
5173 /api/v1/plugins/{npmName}/registered-settings:
5177 summary: Get a plugin's registered settings
5182 - $ref: '#/components/parameters/npmName'
5185 description: successful operation
5190 additionalProperties: true
5192 description: plugin not found
5194 /api/v1/metrics/playback:
5196 summary: Create playback metrics
5197 description: These metrics are exposed by OpenTelemetry metrics exporter if enabled.
5204 $ref: '#/components/schemas/PlaybackMetricCreate'
5207 description: successful operation
5210 - url: 'https://peertube2.cpy.re'
5211 description: Live Test Server (live data - latest nightly version)
5212 - url: 'https://peertube3.cpy.re'
5213 description: Live Test Server (live data - latest RC version)
5214 - url: 'https://peertube.cpy.re'
5215 description: Live Test Server (live data - stable version)
5222 description: Offset used to paginate results
5230 description: "Number of items to return"
5240 description: Sort column
5248 description: Plain text search, applied to various parts of the model depending on endpoint
5256 If the administrator enabled search index support, you can override the default search target.
5259 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
5260 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
5261 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
5262 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
5263 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
5264 * 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
5265 the data from the origin instance API
5288 Sort videos by criteria (prefixing with `-` means `DESC` order):
5289 * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
5290 * `best` - Same than `hot`, but also takes into account user video history
5291 * `trending` - Sort videos by recent views ("recent" is defined by the admin)
5292 * `views` - Sort videos using their `views` counter
5293 * `publishedAt` - Sort by video publication date (when it became publicly available)
5299 Sort videos by criteria (prefixing with `-` means `DESC` order):
5314 description: Sort comments by criteria
5324 description: Sort blocklists by criteria
5340 description: Plain text search that will match with user usernames or emails
5347 description: Filter results down to (un)banned users
5354 description: Sort users by criteria
5365 description: Sort abuses by criteria
5372 videoRedundanciesSort:
5376 description: Sort abuses by criteria
5385 description: Sort followers by criteria
5394 description: The username or handle of the account
5397 example: chocobozzz | chocobozzz@example.org
5402 description: Entity id
5404 $ref: '#/components/schemas/id'
5409 description: The object id, uuid or short uuid
5412 - $ref: '#/components/schemas/id'
5413 - $ref: '#/components/schemas/UUIDv4'
5414 - $ref: '#/components/schemas/shortUUID'
5419 description: Playlist id
5421 $ref: '#/components/schemas/VideoPlaylist/properties/id'
5423 name: playlistElementId
5426 description: Playlist element id
5428 $ref: '#/components/schemas/id'
5433 description: Abuse id
5435 $ref: '#/components/schemas/Abuse/properties/id'
5437 name: abuseMessageId
5440 description: Abuse message id
5442 $ref: '#/components/schemas/AbuseMessage/properties/id'
5444 name: captionLanguage
5447 description: The caption language
5449 $ref: '#/components/schemas/VideoLanguageSet'
5454 description: The video channel handle
5457 example: my_username | my_username@example.com
5462 description: Channel Sync id
5464 $ref: '#/components/schemas/Abuse/properties/id'
5466 name: subscriptionHandle
5469 description: The subscription handle
5472 example: my_username | my_username@example.com
5477 description: The thread id (root comment id)
5484 description: The comment id
5486 $ref: '#/components/schemas/VideoComment/properties/id'
5491 description: whether or not the video is a live
5498 description: category id of the video (see [/videos/categories](#operation/getCategories))
5501 - $ref: '#/components/schemas/VideoCategorySet'
5504 $ref: '#/components/schemas/VideoCategorySet'
5511 description: tag(s) of the video
5525 description: tag(s) of the video, where all should be present in the video
5538 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
5541 - $ref: '#/components/schemas/VideoLanguageSet'
5544 $ref: '#/components/schemas/VideoLanguageSet'
5551 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5554 - $ref: '#/components/schemas/VideoLicenceSet'
5557 $ref: '#/components/schemas/VideoLicenceSet'
5564 description: if you don't need the `total` in the response
5575 description: whether to include nsfw videos, if any
5587 description: '**PeerTube >= 4.0** Display only local or remote videos'
5594 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
5596 name: hasWebtorrentFiles
5601 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
5607 $ref: '#/components/schemas/VideoPrivacySet'
5608 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
5622 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
5626 - `1` NOT_PUBLISHED_STATE
5637 description: list of uris to check if each is part of the user subscriptions
5647 description: name of the plugin/theme on npmjs.com or in its package.json
5650 example: peertube-plugin-auth-ldap
5655 description: job type
5659 - activitypub-follow
5660 - activitypub-http-broadcast
5661 - activitypub-http-fetcher
5662 - activitypub-http-unicast
5667 - videos-views-stats
5668 - activitypub-refresher
5671 - video-channel-import
5695 description: Filename
5699 name: videoFileToken
5702 description: Video file token [generated](#operation/requestVideoToken) by PeerTube so you don't need to provide an OAuth token in the request header.
5710 Authenticating via OAuth requires the following steps:
5711 - Have an activated account
5712 - [Generate] an access token for that account at `/api/v1/users/token`.
5713 - Make requests with the *Authorization: Bearer <token\>* header
5714 - Profit, depending on the role assigned to the account
5716 Note that the __access token is valid for 1 day__ and is given
5717 along with a __refresh token valid for 2 weeks__.
5719 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5723 tokenUrl: /api/v1/users/token
5726 moderator: Moderator scope
5729 # Reusable core properties
5737 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5738 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5743 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5744 example: 2y84q2MQUMWPbiEcxNXMgC
5747 description: immutable name of the user, used to find or mention its actor
5749 pattern: '/^[a-z0-9._]+$/'
5754 description: immutable name of the channel, used to interact with its actor
5755 example: framasoft_videos
5756 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5767 description: category id of the video (see [/videos/categories](#operation/getCategories))
5769 VideoConstantNumber-Category:
5772 $ref: '#/components/schemas/VideoCategorySet'
5775 example: Science & Technology
5779 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5781 VideoConstantNumber-Licence:
5784 $ref: '#/components/schemas/VideoLicenceSet'
5787 example: Attribution - Share Alike
5791 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5793 VideoConstantString-Language:
5796 $ref: '#/components/schemas/VideoLanguageSet'
5801 VideoPlaylistPrivacySet:
5807 description: Video playlist privacy policy (see [/video-playlists/privacies])
5808 VideoPlaylistPrivacyConstant:
5811 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5815 VideoPlaylistTypeSet:
5820 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5821 VideoPlaylistTypeConstant:
5824 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5835 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5836 VideoPrivacyConstant:
5839 $ref: '#/components/schemas/VideoPrivacySet'
5847 additionalProperties:
5848 x-additionalPropertiesName: account
5857 additionalProperties:
5858 x-additionalPropertiesName: host
5879 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5886 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5889 LiveVideoLatencyMode:
5895 description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
5916 - `4`: Waiting for live stream
5918 - `6`: To move to an external storage (object storage...)
5919 - `7`: Transcoding failed
5920 - `8`: Moving to an external storage failed
5921 - `9`: To edit using studio edition feature
5931 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5935 $ref: '#/components/schemas/AbuseStateSet'
5938 AbusePredefinedReasons:
5951 example: [spamOrMisleading]
5956 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5958 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5960 VideoResolutionConstant:
5961 description: resolutions and their labels for the video
5964 $ref: '#/components/schemas/VideoResolutionSet'
5968 VideoScheduledUpdate:
5971 $ref: '#/components/schemas/VideoPrivacySet'
5975 description: When to update the video
5995 $ref: '#/components/schemas/ActorImage'
5996 VideoChannelSummary:
5999 $ref: '#/components/schemas/id'
6013 $ref: '#/components/schemas/ActorImage'
6027 - $ref: '#/components/schemas/Video'
6032 $ref: '#/components/schemas/id'
6036 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
6037 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6039 $ref: '#/components/schemas/VideoResolutionConstant'
6042 description: Video file size in bytes
6045 description: Direct URL of the torrent file
6049 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
6053 description: Direct URL of the video
6057 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
6061 description: Frames per second of the video file
6065 description: URL dereferencing the output of ffprobe on the file
6066 VideoStreamingPlaylists:
6071 $ref: '#/components/schemas/id'
6079 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
6080 VideoStreamingPlaylists-HLS:
6091 Video files associated to this playlist.
6093 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
6095 $ref: '#/components/schemas/VideoFile'
6107 $ref: '#/components/schemas/Video/properties/id'
6109 $ref: '#/components/schemas/Video/properties/uuid'
6111 $ref: '#/components/schemas/Video/properties/name'
6115 description: object id for the video
6117 - $ref: '#/components/schemas/id'
6119 description: universal identifier for the video, that can be used across instances
6121 - $ref: '#/components/schemas/UUIDv4'
6124 - $ref: '#/components/schemas/shortUUID'
6130 example: 2017-10-01T10:52:46.396Z
6131 description: time at which the video object was first drafted
6135 example: 2018-10-01T10:52:46.396Z
6136 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
6140 example: 2021-05-04T08:01:01.502Z
6141 description: last time the video's metadata was modified
6142 originallyPublishedAt:
6145 example: 2010-10-01T10:52:46.396Z
6146 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
6149 - $ref: '#/components/schemas/VideoConstantNumber-Category'
6150 description: category in which the video is classified
6153 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
6154 description: licence under which the video is distributed
6157 - $ref: '#/components/schemas/VideoConstantString-Language'
6158 description: main language used in the video
6161 - $ref: '#/components/schemas/VideoPrivacyConstant'
6162 description: privacy policy used to distribute the video
6166 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
6167 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
6171 truncated description of the video, written in Markdown.
6172 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
6177 description: duration of the video in seconds
6182 description: title of the video
6183 example: What is PeerTube?
6188 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
6191 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
6194 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
6211 - $ref: '#/components/schemas/VideoStateConstant'
6212 description: represents the internal state of the video processing within the PeerTube instance
6216 - $ref: '#/components/schemas/VideoScheduledUpdate'
6224 $ref: '#/components/schemas/AccountSummary'
6226 $ref: '#/components/schemas/VideoChannelSummary'
6235 - $ref: '#/components/schemas/Video'
6240 description: If the video is a live, you have the amount of current viewers
6243 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
6244 description: path at which to get the full description of maximum `10000` characters
6247 description: A text tell the audience how to support the video creator
6248 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6252 $ref: '#/components/schemas/VideoChannel'
6254 $ref: '#/components/schemas/Account'
6256 example: [flowers, gardening]
6274 - https://peertube2.cpy.re/tracker/announce
6275 - wss://peertube2.cpy.re/tracker/socket
6279 $ref: '#/components/schemas/VideoFile'
6281 WebTorrent/raw video files. If WebTorrent is disabled on the server:
6283 - field will be empty
6284 - video files will be found in `streamingPlaylists[].files` field
6288 $ref: '#/components/schemas/VideoStreamingPlaylists'
6290 HLS playlists/manifest files. If HLS is disabled on the server:
6292 - field will be empty
6293 - video files will be found in `files` field
6294 FileRedundancyInformation:
6297 $ref: '#/components/schemas/id'
6322 $ref: '#/components/schemas/id'
6329 $ref: '#/components/schemas/UUIDv4'
6336 $ref: '#/components/schemas/FileRedundancyInformation'
6340 $ref: '#/components/schemas/FileRedundancyInformation'
6341 VideoImportStateConstant:
6349 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
6356 additionalProperties: false
6360 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
6361 required: [targetUrl]
6364 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6365 required: [magnetUri]
6368 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
6369 required: [torrentfile]
6370 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6379 - $ref: '#/components/schemas/id'
6383 description: remote URL where to find the import's source video
6384 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
6388 description: magnet URI allowing to resolve the import's source video
6389 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6394 description: Torrent file containing only the video file
6401 - $ref: '#/components/schemas/VideoImportStateConstant'
6417 - $ref: '#/components/schemas/Video'
6427 $ref: '#/components/schemas/VideoImport'
6431 $ref: '#/components/schemas/id'
6434 example: The video is a spam
6438 $ref: '#/components/schemas/AbusePredefinedReasons'
6440 $ref: '#/components/schemas/Account'
6442 $ref: '#/components/schemas/AbuseStateConstant'
6445 example: Decided to ban the server since it spams us regularly
6449 $ref: '#/components/schemas/VideoInfo'
6456 $ref: '#/components/schemas/id'
6467 $ref: '#/components/schemas/AccountSummary'
6471 $ref: '#/components/schemas/id'
6473 $ref: '#/components/schemas/Video/properties/id'
6485 $ref: '#/components/schemas/UUIDv4'
6503 $ref: '#/components/schemas/id'
6505 $ref: '#/components/schemas/UUIDv4'
6508 - $ref: '#/components/schemas/shortUUID'
6531 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
6533 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
6535 $ref: '#/components/schemas/AccountSummary'
6537 $ref: '#/components/schemas/VideoChannelSummary'
6541 $ref: '#/components/schemas/id'
6548 description: Text of the comment
6550 example: This video is wonderful!
6552 $ref: '#/components/schemas/id'
6556 - $ref: '#/components/schemas/id'
6558 $ref: '#/components/schemas/Video/properties/id'
6573 totalRepliesFromVideoAuthor:
6580 $ref: '#/components/schemas/Account'
6581 VideoCommentThreadTree:
6584 $ref: '#/components/schemas/VideoComment'
6588 $ref: '#/components/schemas/VideoCommentThreadTree'
6592 $ref: '#/components/schemas/VideoConstantString-Language'
6614 $ref: '#/components/schemas/id'
6625 $ref: '#/components/schemas/ActorImage'
6629 $ref: '#/components/schemas/id'
6634 description: immutable name of the actor, used to find or mention it
6636 - $ref: '#/components/schemas/username'
6640 description: server on which the actor is resident
6641 hostRedundancyAllowed:
6643 description: whether this actor's host allows redundancy of its videos
6647 description: number of actors subscribed to by this actor, as seen by this instance
6651 description: number of followers of this actor, as seen by this instance
6660 - $ref: '#/components/schemas/Actor'
6663 description: object id for the user tied to this account
6665 - $ref: '#/components/schemas/User/properties/id'
6668 description: editable name of the account, displayed in its representations
6673 description: text or bio displayed on the account's profile
6681 description: timestamp within the video, in seconds
6688 Event since last viewing call:
6689 * `seek` - If the user seeked the video
6712 VideoStatsRetention:
6724 VideoStatsTimeserie:
6801 allowedForCurrentIP:
6803 requiresEmailVerification:
6821 $ref: '#/components/schemas/VideoResolutionSet'
6838 videoChannelSynchronization:
6911 example: 16810141515
6952 description: URL of the current user page
6959 description: Stack trace of the error if there is one
6962 description: User agent of the web browser that sends the message
6965 description: Additional information regarding this log
6975 totalDailyActiveUsers:
6977 totalWeeklyActiveUsers:
6979 totalMonthlyActiveUsers:
6983 totalLocalVideoViews:
6985 description: Total video views made on the instance
6986 totalLocalVideoComments:
6988 description: Total comments made by local users
6989 totalLocalVideoFilesSize:
6995 totalLocalVideoChannels:
6997 totalLocalDailyActiveVideoChannels:
6999 totalLocalWeeklyActiveVideoChannels:
7001 totalLocalMonthlyActiveVideoChannels:
7003 totalLocalPlaylists:
7005 totalInstanceFollowers:
7007 totalInstanceFollowing:
7024 totalActivityPubMessagesProcessed:
7026 totalActivityPubMessagesSuccesses:
7028 totalActivityPubMessagesErrors:
7031 activityPubMessagesProcessedPerSecond:
7033 totalActivityPubMessagesWaiting:
7110 requiresEmailVerification:
7125 description: Settings that apply to new users, if registration is enabled
7129 example: 16810141515
7135 description: Settings pertaining to transcoding jobs
7139 allowAdditionalExtensions:
7141 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
7144 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
7147 description: Amount of threads used by ffmpeg for 1 transcoding job
7150 description: Amount of transcoding jobs to execute in parallel
7156 New profiles can be added by plugins ; available in core PeerTube: 'default'.
7159 description: Resolutions to transcode _new videos_ to
7181 description: WebTorrent-specific settings
7187 description: HLS-specific settings
7207 video_channel_synchronization:
7242 $ref: '#/components/schemas/id'
7244 $ref: '#/components/schemas/Actor'
7246 $ref: '#/components/schemas/Actor'
7249 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
7262 PredefinedAbuseReasons:
7263 description: Reason categories that help triage reports
7281 $ref: '#/components/schemas/id'
7293 - activitypub-http-unicast
7294 - activitypub-http-broadcast
7295 - activitypub-http-fetcher
7296 - activitypub-follow
7301 - videos-views-stats
7302 - activitypub-refresher
7304 - video-channel-import
7307 additionalProperties: true
7310 additionalProperties: true
7326 $ref: '#/components/schemas/id'
7331 $ref: '#/components/schemas/id'
7332 VideoUploadRequestCommon:
7335 description: Video name
7337 example: What is PeerTube?
7341 description: Channel id that will contain this video
7346 $ref: '#/components/schemas/VideoPrivacySet'
7348 $ref: '#/components/schemas/VideoCategorySet'
7350 $ref: '#/components/schemas/VideoLicenceSet'
7352 $ref: '#/components/schemas/VideoLanguageSet'
7354 description: Video description
7357 **[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)**
7359 description: Whether or not we wait transcoding before publish the video
7362 description: A text tell the audience how to support the video creator
7363 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7366 description: Whether or not this video contains sensitive content
7369 description: Video tags (maximum 5 tags each between 2 and 30 characters)
7382 description: Enable or disable comments for this video
7385 description: Enable or disable downloading for this video
7387 originallyPublishedAt:
7388 description: Date when the content was originally published
7392 $ref: '#/components/schemas/VideoScheduledUpdate'
7394 description: Video thumbnail file
7398 description: Video preview file
7404 VideoUploadRequestLegacy:
7406 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7412 description: Video file
7415 VideoUploadRequestResumable:
7417 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7423 description: Video filename including extension
7426 example: what_is_peertube.mp4
7428 description: Video thumbnail file
7432 description: Video preview file
7435 VideoUploadResponse:
7441 $ref: '#/components/schemas/Video/properties/id'
7443 $ref: '#/components/schemas/Video/properties/uuid'
7445 $ref: '#/components/schemas/Video/properties/shortUUID'
7446 CommentThreadResponse:
7455 $ref: '#/components/schemas/VideoComment'
7456 CommentThreadPostResponse:
7459 $ref: '#/components/schemas/VideoComment'
7479 $ref: '#/components/schemas/Video'
7483 $ref: '#/components/schemas/Account'
7486 description: Automatically start playing the upcoming video after the currently playing video
7487 autoPlayNextVideoPlaylist:
7489 description: Automatically start playing the video on the playlist after the currently playing video
7492 description: Automatically start playing the video on the watch page
7502 description: The user email
7505 description: Has the user confirmed their email address?
7508 - $ref: '#/components/schemas/id'
7512 description: Auth plugin to use to authenticate the user
7516 noInstanceConfigWarningModal:
7518 noAccountSetupWarningModal:
7523 $ref: '#/components/schemas/NSFWPolicy'
7528 $ref: '#/components/schemas/UserRole'
7537 description: Theme enabled by this user
7539 $ref: '#/components/schemas/username'
7543 $ref: '#/components/schemas/VideoChannel'
7546 description: The user video quota in bytes
7550 description: The user daily video quota in bytes
7554 description: Enable P2P in the player
7557 - $ref: '#/components/schemas/User'
7559 # optionally present fields: they require WITH_STATS scope
7562 description: Count of videos published
7565 description: Count of reports/abuses of which the user is a target
7566 abusesAcceptedCount:
7568 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
7571 description: Count of reports/abuses created by the user
7574 description: Count of comments published
7578 $ref: '#/components/schemas/username'
7580 $ref: '#/components/schemas/password'
7584 description: The user email
7587 description: The user video quota in bytes
7591 description: The user daily video quota in bytes
7594 $ref: '#/components/schemas/usernameChannel'
7596 $ref: '#/components/schemas/UserRole'
7598 $ref: '#/components/schemas/UserAdminFlags'
7609 description: The updated email of the user
7611 - $ref: '#/components/schemas/User/properties/email'
7614 description: Set the email as verified
7617 description: The updated video quota of the user in bytes
7620 description: The updated daily video quota of the user in bytes
7624 description: The auth plugin to use to authenticate the user
7625 example: 'peertube-plugin-auth-saml2'
7627 $ref: '#/components/schemas/UserRole'
7629 $ref: '#/components/schemas/UserAdminFlags'
7631 $ref: '#/components/schemas/password'
7633 # see shared/models/users/user-update-me.model.ts:
7636 $ref: '#/components/schemas/password'
7638 $ref: '#/components/schemas/password'
7640 description: new email used for login and service communications
7642 - $ref: '#/components/schemas/User/properties/email'
7645 description: new name of the user in its representations
7650 description: new NSFW display policy
7657 description: whether to enable P2P in the player or not
7660 description: new preference regarding playing videos automatically
7663 description: new preference regarding playing following videos automatically
7664 autoPlayNextVideoPlaylist:
7666 description: new preference regarding playing following playlist videos automatically
7667 videosHistoryEnabled:
7669 description: whether to keep track of watched history or not
7674 description: list of languages to filter videos down to
7677 noInstanceConfigWarningModal:
7679 noAccountSetupWarningModal:
7686 $ref: '#/components/schemas/id'
7693 description: Rating of the video
7700 $ref: '#/components/schemas/Video'
7707 description: Rating of the video
7714 description: immutable name of the user, used to find or mention its actor
7716 - $ref: '#/components/schemas/username'
7718 $ref: '#/components/schemas/password'
7722 description: email of the user, used for login or service communications
7725 description: editable name of the user, displayed in its representations
7730 description: channel base information used to create the first channel of the user
7733 $ref: '#/components/schemas/usernameChannel'
7745 pattern: /^[a-z0-9]$/
7748 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
7751 pattern: /^[a-zA-Z0-9]$/
7754 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
7755 OAuthToken-password:
7757 - $ref: '#/components/schemas/OAuthClient'
7767 $ref: '#/components/schemas/User/properties/username'
7769 $ref: '#/components/schemas/password'
7776 OAuthToken-refresh_token:
7778 - $ref: '#/components/schemas/OAuthClient'
7789 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
7798 - $ref: '#/components/schemas/Actor'
7803 description: editable name of the channel, displayed in its representations
7804 example: Videos of Framasoft
7809 example: Videos made with <3 by Framasoft
7814 description: text shown by default on all videos of this channel, to tell the audience how to support it
7815 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7828 $ref: '#/components/schemas/ActorImage'
7837 $ref: '#/components/schemas/UUIDv4'
7841 - $ref: '#/components/schemas/VideoChannel'
7844 description: username of the channel to create
7846 - $ref: '#/components/schemas/usernameChannel'
7852 - $ref: '#/components/schemas/VideoChannel'
7854 bulkVideosSupportUpdate:
7856 description: Update the support field for all videos of this channel
7866 - $ref: '#/components/schemas/VideoChannel'
7867 - $ref: '#/components/schemas/Actor'
7869 ImportVideosInChannelCreate:
7874 example: https://youtube.com/c/UC_myfancychannel
7877 description: If part of a channel sync process, specify its id to assign video imports to this channel synchronization
7879 - 'externalChannelUrl'
7885 $ref: '#/components/schemas/id'
7897 example: 'https://youtube.com/c/UC_myfancychannel'
7906 $ref: '#/components/schemas/VideoChannel'
7907 VideoChannelSyncList:
7917 - $ref: '#/components/schemas/VideoChannelSync'
7918 VideoChannelSyncCreate:
7923 example: https://youtube.com/c/UC_myfancychannel
7925 $ref: '#/components/schemas/id'
7929 name: 'media:peerLink'
7938 - application/x-bittorrent
7944 name: 'media:content'
7975 VideoCommentsForXML:
8010 description: video watch page URL
8013 description: video canonical URL
8017 description: video publication date
8020 description: video description
8023 description: video description
8026 description: publisher user name
8029 description: video category (MRSS)
8032 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
8047 description: video embed path, relative to the canonical URL domain (MRSS)
8056 description: video watch path, relative to the canonical URL domain (MRSS)
8077 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
8078 'media:description':
8085 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
8088 description: main streamable file for the video
8098 - application/x-bittorrent
8107 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)
8110 - $ref: '#/components/schemas/MRSSPeerLink'
8111 - $ref: '#/components/schemas/MRSSGroupContent'
8112 NotificationSettingValue:
8129 $ref: '#/components/schemas/id'
8133 Notification type, following the `UserNotificationType` enum:
8135 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
8137 - `2` NEW_COMMENT_ON_MY_VIDEO
8139 - `3` NEW_ABUSE_FOR_MODERATORS
8141 - `4` BLACKLIST_ON_MY_VIDEO
8143 - `5` UNBLACKLIST_ON_MY_VIDEO
8145 - `6` MY_VIDEO_PUBLISHED
8147 - `7` MY_VIDEO_IMPORT_SUCCESS
8149 - `8` MY_VIDEO_IMPORT_ERROR
8151 - `9` NEW_USER_REGISTRATION
8155 - `11` COMMENT_MENTION
8157 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
8159 - `13` NEW_INSTANCE_FOLLOWER
8161 - `14` AUTO_INSTANCE_FOLLOWING
8163 - `15` ABUSE_STATE_CHANGE
8165 - `16` ABUSE_NEW_MESSAGE
8167 - `17` NEW_PLUGIN_VERSION
8169 - `18` NEW_PEERTUBE_VERSION
8175 - $ref: '#/components/schemas/VideoInfo'
8179 $ref: '#/components/schemas/ActorInfo'
8185 $ref: '#/components/schemas/id'
8188 $ref: '#/components/schemas/VideoInfo'
8193 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
8203 $ref: '#/components/schemas/id'
8207 $ref: '#/components/schemas/VideoInfo'
8209 $ref: '#/components/schemas/ActorInfo'
8215 $ref: '#/components/schemas/id'
8218 - $ref: '#/components/schemas/VideoInfo'
8224 $ref: '#/components/schemas/id'
8227 - $ref: '#/components/schemas/VideoInfo'
8231 - $ref: '#/components/schemas/ActorInfo'
8237 $ref: '#/components/schemas/id'
8239 $ref: '#/components/schemas/ActorInfo'
8267 NotificationListResponse:
8276 $ref: '#/components/schemas/Notification'
8281 example: peertube-plugin-auth-ldap
8309 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
8312 additionalProperties: true
8328 $ref: '#/components/schemas/Plugin'
8335 description: User can stream multiple times in a permanent live
8338 description: User can select live latency mode if enabled by the instance
8339 $ref: '#/components/schemas/LiveVideoLatencyMode'
8345 description: Included in the response if an appropriate token is provided
8348 description: Included in the response if an appropriate token is provided
8351 description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
8355 description: User can stream multiple times in a permanent live
8358 description: User can select live latency mode if enabled by the instance
8359 $ref: '#/components/schemas/LiveVideoLatencyMode'
8361 RequestTwoFactorResponse:
8368 description: The token to send to confirm this request
8371 description: The OTP secret
8374 description: The OTP URI
8376 VideoStudioCreateTask:
8424 title: add-watermark
8438 LiveVideoSessionResponse:
8445 description: Start date of the live session
8450 description: End date of the live session
8461 Error type if an error occurred during the live session:
8462 - `1`: Bad socket health (transcoding is too slow)
8463 - `2`: Max duration exceeded
8464 - `3`: Quota exceeded
8465 - `4`: Quota FFmpeg error
8466 - `5`: Video has been blacklisted during the live
8469 description: Video replay information
8474 $ref: '#/components/schemas/UUIDv4'
8476 $ref: '#/components/schemas/shortUUID'
8478 PlaybackMetricCreate:
8483 - 'p2p-media-loader'
8487 description: Current player video resolution
8490 description: Current player video fps
8493 description: How many resolution changes occured since the last metric creation
8496 description: How many errors occured since the last metric creation
8499 description: How many bytes were downloaded with P2P since the last metric creation
8500 downloadedBytesHTTP:
8502 description: How many bytes were downloaded with HTTP since the last metric creation
8505 description: How many bytes were uploaded with P2P since the last metric creation
8508 - $ref: '#/components/schemas/id'
8509 - $ref: '#/components/schemas/UUIDv4'
8510 - $ref: '#/components/schemas/shortUUID'
8515 - downloadedBytesP2P
8516 - downloadedBytesHTTP
8522 'https://search.example.org/api/v1/search/videos':
8524 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
8527 description: successful operation
8531 $ref: '#/components/schemas/VideoListResponse'