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#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#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#instances-redundancy
218 Managing plugins installed from a local path or from NPM, or search for new ones.
220 url: https://docs.joinpeertube.org/api/plugins
223 Abuses deal with reports of local or remote videos/comments/accounts alike.
226 Operations dealing with listing, uploading, fetching or modifying videos.
229 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
233 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
234 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
236 You can upload videos more reliably by using the resumable variant. Its protocol lets
237 you resume an upload operation after a network interruption or other transmission failure,
238 saving time and bandwidth in the event of network failures.
240 Favor using resumable uploads in any of the following cases:
241 - You are transferring large files
242 - The likelihood of a network interruption is high
243 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
244 such as a mobile device
248 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
249 - _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file
250 - _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file
252 The import function is practical when the desired video/audio is available online. It makes PeerTube
253 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
254 - name: Video Imports
255 description: Operations dealing with listing, adding and removing video imports.
256 - name: Channels Sync
257 description: Operations dealing with synchronizing PeerTube user's channel with channels of other platforms
258 - name: Video Captions
259 description: Operations dealing with listing, adding and removing closed captions of a video.
260 - name: Video Channels
261 description: Operations dealing with the creation, modification and listing of videos within a channel.
262 - name: Video Comments
264 Operations dealing with comments to a video. Comments are organized in threads: adding a
265 comment in response to the video starts a thread, adding a reply to a comment adds it to
266 its root comment thread.
268 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
270 description: Like/dislike a video.
271 - name: Video Playlists
272 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
274 description: Operations on video files
275 - name: Video Transcoding
276 description: Video transcoding related operations
278 description: Video statistics
280 description: Server syndication feeds of videos
283 The search helps to find _videos_ or _channels_ from within the instance and beyond.
284 Videos from other instances federated by the instance (that is, instances
285 followed by the instance) can be found via keywords and other criteria of
288 Administrators can also enable the use of a remote search system, indexing
289 videos and channels not could be not federated by the instance.
291 description: Get and update the custom homepage
292 - name: Video Mirroring
294 PeerTube instances can mirror videos from one another, and help distribute some videos.
296 For importing videos as your own, refer to [video imports](#operation/importVideo).
302 - name: Static endpoints
331 - Video Ownership Change
351 - Instance Redundancy
357 '/static/webseed/{filename}':
361 summary: Get public WebTorrent video file
363 - $ref: '#/components/parameters/staticFilename'
366 description: successful operation
368 description: not found
369 '/static/webseed/private/{filename}':
373 summary: Get private WebTorrent video file
375 - $ref: '#/components/parameters/staticFilename'
376 - $ref: '#/components/parameters/videoFileToken'
381 description: successful operation
383 description: invalid auth
385 description: not found
387 '/static/streaming-playlists/hls/{filename}':
391 summary: Get public HLS video file
393 - $ref: '#/components/parameters/staticFilename'
398 description: successful operation
400 description: invalid auth
402 description: not found
403 '/static/streaming-playlists/hls/private/{filename}':
407 summary: Get private HLS video file
409 - $ref: '#/components/parameters/staticFilename'
410 - $ref: '#/components/parameters/videoFileToken'
411 - $ref: '#/components/parameters/reinjectVideoFileToken'
416 description: successful operation
418 description: invalid auth
420 description: not found
423 '/feeds/video-comments.{format}':
427 summary: List comments on videos
428 operationId: getSyndicatedComments
433 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
446 description: 'limit listing to a specific video'
451 description: 'limit listing to a specific account'
456 description: 'limit listing to a specific account'
459 - name: videoChannelId
461 description: 'limit listing to a specific video channel'
464 - name: videoChannelName
466 description: 'limit listing to a specific video channel'
471 description: successful operation
476 default: 'max-age=900' # 15 min cache
480 $ref: '#/components/schemas/VideoCommentsForXML'
483 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
486 $ref: '#/components/schemas/VideoCommentsForXML'
489 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
492 $ref: '#/components/schemas/VideoCommentsForXML'
495 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
496 application/atom+xml:
498 $ref: '#/components/schemas/VideoCommentsForXML'
501 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
507 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
509 x-summary: field inconsistencies
512 - videoId filter is mixed with a channel filter
514 description: video, video channel or account not found
516 description: accept header unsupported
518 '/feeds/videos.{format}':
523 operationId: getSyndicatedVideos
528 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
541 description: 'limit listing to a specific account'
546 description: 'limit listing to a specific account'
549 - name: videoChannelId
551 description: 'limit listing to a specific video channel'
554 - name: videoChannelName
556 description: 'limit listing to a specific video channel'
559 - $ref: '#/components/parameters/sort'
560 - $ref: '#/components/parameters/nsfw'
561 - $ref: '#/components/parameters/isLocal'
562 - $ref: '#/components/parameters/include'
563 - $ref: '#/components/parameters/privacyOneOf'
564 - $ref: '#/components/parameters/hasHLSFiles'
565 - $ref: '#/components/parameters/hasWebtorrentFiles'
568 description: successful operation
573 default: 'max-age=900' # 15 min cache
577 $ref: '#/components/schemas/VideosForXML'
580 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
583 $ref: '#/components/schemas/VideosForXML'
586 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
589 $ref: '#/components/schemas/VideosForXML'
592 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
593 application/atom+xml:
595 $ref: '#/components/schemas/VideosForXML'
598 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
604 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
606 description: video channel or account not found
608 description: accept header unsupported
610 '/feeds/subscriptions.{format}':
614 summary: List videos of subscriptions tied to a token
615 operationId: getSyndicatedSubscriptionVideos
620 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
633 description: limit listing to a specific account
639 description: private token allowing access
643 - $ref: '#/components/parameters/sort'
644 - $ref: '#/components/parameters/nsfw'
645 - $ref: '#/components/parameters/isLocal'
646 - $ref: '#/components/parameters/include'
647 - $ref: '#/components/parameters/privacyOneOf'
648 - $ref: '#/components/parameters/hasHLSFiles'
649 - $ref: '#/components/parameters/hasWebtorrentFiles'
652 description: successful operation
657 default: 'max-age=900' # 15 min cache
661 $ref: '#/components/schemas/VideosForXML'
664 $ref: '#/components/schemas/VideosForXML'
667 $ref: '#/components/schemas/VideosForXML'
668 application/atom+xml:
670 $ref: '#/components/schemas/VideosForXML'
675 description: accept header unsupported
677 '/api/v1/accounts/{name}':
681 summary: Get an account
682 operationId: getAccount
684 - $ref: '#/components/parameters/name'
687 description: successful operation
691 $ref: '#/components/schemas/Account'
693 description: account not found
695 '/api/v1/accounts/{name}/videos':
700 summary: 'List videos of an account'
701 operationId: getAccountVideos
703 - $ref: '#/components/parameters/name'
704 - $ref: '#/components/parameters/categoryOneOf'
705 - $ref: '#/components/parameters/isLive'
706 - $ref: '#/components/parameters/tagsOneOf'
707 - $ref: '#/components/parameters/tagsAllOf'
708 - $ref: '#/components/parameters/licenceOneOf'
709 - $ref: '#/components/parameters/languageOneOf'
710 - $ref: '#/components/parameters/nsfw'
711 - $ref: '#/components/parameters/isLocal'
712 - $ref: '#/components/parameters/include'
713 - $ref: '#/components/parameters/privacyOneOf'
714 - $ref: '#/components/parameters/hasHLSFiles'
715 - $ref: '#/components/parameters/hasWebtorrentFiles'
716 - $ref: '#/components/parameters/skipCount'
717 - $ref: '#/components/parameters/start'
718 - $ref: '#/components/parameters/count'
719 - $ref: '#/components/parameters/videosSort'
722 description: successful operation
726 $ref: '#/components/schemas/VideoListResponse'
730 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
731 .then(function(response) {
732 return response.json()
733 }).then(function(data) {
739 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
745 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
747 http = Net::HTTP.new(uri.host, uri.port)
750 response = http.get(uri.request_uri)
752 puts JSON.parse(response.read_body)
757 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
762 '/api/v1/accounts/{name}/followers':
766 summary: 'List followers of an account'
769 operationId: getAccountFollowers
771 - $ref: '#/components/parameters/name'
772 - $ref: '#/components/parameters/start'
773 - $ref: '#/components/parameters/count'
774 - $ref: '#/components/parameters/followersSort'
775 - $ref: '#/components/parameters/search'
778 description: successful operation
790 $ref: '#/components/schemas/Follow'
796 summary: List accounts
797 operationId: getAccounts
799 - $ref: '#/components/parameters/start'
800 - $ref: '#/components/parameters/count'
801 - $ref: '#/components/parameters/sort'
804 description: successful operation
810 $ref: '#/components/schemas/Account'
816 summary: Get instance public configuration
817 operationId: getConfig
820 description: successful operation
824 $ref: '#/components/schemas/ServerConfig'
827 externalValue: https://peertube2.cpy.re/api/v1/config
829 /api/v1/config/about:
831 summary: Get instance "About" information
832 operationId: getAbout
837 description: successful operation
841 $ref: '#/components/schemas/ServerConfigAbout'
844 externalValue: https://peertube2.cpy.re/api/v1/config/about
846 /api/v1/config/custom:
848 summary: Get instance runtime configuration
849 operationId: getCustomConfig
857 description: successful operation
861 $ref: '#/components/schemas/ServerConfigCustom'
863 summary: Set instance runtime configuration
864 operationId: putCustomConfig
872 description: successful operation
874 x-summary: field inconsistencies
877 - the emailer is disabled and the instance is open to registrations
878 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
880 summary: Delete instance runtime configuration
881 operationId: delCustomConfig
889 description: successful operation
891 /api/v1/custom-pages/homepage/instance:
893 summary: Get instance custom homepage
898 description: No homepage set
900 description: successful operation
904 $ref: '#/components/schemas/CustomHomepage'
906 summary: Set instance custom homepage
920 description: content of the homepage, that will be injected in the client
923 description: successful operation
927 summary: Pause job queue
935 description: successful operation
939 summary: Resume job queue
947 description: successful operation
949 /api/v1/jobs/{state}:
951 summary: List instance jobs
962 description: The state of the job ('' for for no filter)
972 - $ref: '#/components/parameters/jobType'
973 - $ref: '#/components/parameters/start'
974 - $ref: '#/components/parameters/count'
975 - $ref: '#/components/parameters/sort'
978 description: successful operation
991 $ref: '#/components/schemas/Job'
993 /api/v1/server/followers:
997 summary: List instances following the server
999 - $ref: '#/components/parameters/followState'
1000 - $ref: '#/components/parameters/actorType'
1001 - $ref: '#/components/parameters/start'
1002 - $ref: '#/components/parameters/count'
1003 - $ref: '#/components/parameters/sort'
1006 description: successful operation
1018 $ref: '#/components/schemas/Follow'
1020 '/api/v1/server/followers/{nameWithHost}':
1022 summary: Remove or reject a follower to your server
1029 - name: nameWithHost
1032 description: The remote actor handle to remove from your followers
1038 description: successful operation
1040 description: follower not found
1042 '/api/v1/server/followers/{nameWithHost}/reject':
1044 summary: Reject a pending follower to your server
1051 - name: nameWithHost
1054 description: The remote actor handle to remove from your followers
1060 description: successful operation
1062 description: follower not found
1064 '/api/v1/server/followers/{nameWithHost}/accept':
1066 summary: Accept a pending follower to your server
1073 - name: nameWithHost
1076 description: The remote actor handle to remove from your followers
1082 description: successful operation
1084 description: follower not found
1086 /api/v1/server/following:
1090 summary: List instances followed by the server
1092 - $ref: '#/components/parameters/followState'
1093 - $ref: '#/components/parameters/actorType'
1094 - $ref: '#/components/parameters/start'
1095 - $ref: '#/components/parameters/count'
1096 - $ref: '#/components/parameters/sort'
1099 description: successful operation
1111 $ref: '#/components/schemas/Follow'
1118 summary: Follow a list of actors (PeerTube instance, channel or account)
1121 description: successful operation
1123 description: cannot follow a non-HTTPS server
1142 '/api/v1/server/following/{hostOrHandle}':
1144 summary: Unfollow an actor (PeerTube instance, channel or account)
1151 - name: hostOrHandle
1154 description: The hostOrHandle to unfollow
1159 description: successful operation
1161 description: host or handle not found
1165 summary: Create a user
1166 operationId: addUser
1174 description: user created
1178 $ref: '#/components/schemas/AddUserResponse'
1182 operationId: getUser
1184 id: '$response.body#/user/id'
1187 operationId: putUser
1189 id: '$response.body#/user/id'
1190 # DELETE /users/{id}
1192 operationId: delUser
1194 id: '$response.body#/user/id'
1196 description: insufficient authority to create an admin or moderator
1201 $ref: '#/components/schemas/AddUser'
1203 If the smtp server is configured, you can leave the password empty and an email will be sent
1204 asking the user to set it first.
1208 operationId: getUsers
1215 - $ref: '#/components/parameters/usersSearch'
1216 - $ref: '#/components/parameters/usersBlocked'
1217 - $ref: '#/components/parameters/start'
1218 - $ref: '#/components/parameters/count'
1219 - $ref: '#/components/parameters/usersSort'
1222 description: successful operation
1228 $ref: '#/components/schemas/User'
1230 '/api/v1/users/{id}':
1232 - $ref: '#/components/parameters/id'
1234 summary: Delete a user
1240 operationId: delUser
1243 description: successful operation
1250 operationId: getUser
1254 description: include statistics about the user (only available as a moderator/admin)
1259 x-summary: successful operation
1261 As an admin/moderator, you can request a response augmented with statistics about the user's
1262 moderation relations and videos usage, by using the `withStats` parameter.
1267 - $ref: '#/components/schemas/User'
1268 - $ref: '#/components/schemas/UserWithStats'
1270 summary: Update a user
1275 operationId: putUser
1278 description: successful operation
1283 $ref: '#/components/schemas/UpdateUser'
1286 /api/v1/oauth-clients/local:
1288 summary: Login prerequisite
1289 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
1290 operationId: getOAuthClient
1295 description: successful operation
1299 $ref: '#/components/schemas/OAuthClient'
1301 UseOAuthClientToLogin:
1302 operationId: getOAuthToken
1304 client_id: '$response.body#/client_id'
1305 client_secret: '$response.body#/client_secret'
1309 API="https://peertube2.cpy.re/api/v1"
1312 curl -s "$API/oauth-clients/local"
1314 /api/v1/users/token:
1317 operationId: getOAuthToken
1318 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
1323 application/x-www-form-urlencoded:
1326 - $ref: '#/components/schemas/OAuthToken-password'
1327 - $ref: '#/components/schemas/OAuthToken-refresh_token'
1329 propertyName: grant_type
1331 password: '#/components/schemas/OAuthToken-password'
1332 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
1335 description: successful operation
1346 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
1347 description: valid for 1 day
1350 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
1351 description: valid for 2 weeks
1356 refresh_token_expires_in:
1361 x-summary: client or credentials are invalid
1363 Disambiguate via `type`:
1364 - `invalid_client` for an unmatched `client_id`
1365 - `invalid_grant` for unmatched credentials
1367 x-summary: token expired
1369 Disambiguate via `type`:
1370 - default value for a regular authentication failure
1371 - `invalid_token` for an expired token
1376 API="https://peertube2.cpy.re/api/v1"
1377 USERNAME="<your_username>"
1378 PASSWORD="<your_password>"
1381 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1382 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1383 curl -s "$API/users/token" \
1384 --data client_id="$client_id" \
1385 --data client_secret="$client_secret" \
1386 --data grant_type=password \
1387 --data username="$USERNAME" \
1388 --data password="$PASSWORD" \
1389 | jq -r ".access_token"
1391 /api/v1/users/revoke-token:
1394 description: Revokes your access token and its associated refresh token, destroying your current session.
1395 operationId: revokeOAuthToken
1402 description: successful operation
1404 /api/v1/users/ask-send-verify-email:
1406 summary: Resend user verification link
1407 operationId: resendEmailToVerifyUser
1419 description: User email
1422 description: successful operation
1424 /api/v1/users/registrations/ask-send-verify-email:
1426 summary: Resend verification link to registration email
1427 operationId: resendEmailToVerifyRegistration
1438 description: Registration email
1441 description: successful operation
1443 /api/v1/users/{id}/verify-email:
1445 summary: Verify a user
1446 operationId: verifyUser
1448 Following a user registration, the new user will receive an email asking to click a link
1449 containing a secret.
1450 This endpoint can also be used to verify a new email set in the user account.
1455 - $ref: '#/components/parameters/id'
1468 - verificationString
1471 description: successful operation
1473 description: invalid verification string
1475 description: user not found
1477 /api/v1/users/registrations/{registrationId}/verify-email:
1479 summary: Verify a registration email
1480 operationId: verifyRegistrationEmail
1482 Following a user registration request, the user will receive an email asking to click a link
1483 containing a secret.
1487 - $ref: '#/components/parameters/registrationId'
1498 - verificationString
1501 description: successful operation
1503 description: invalid verification string
1505 description: registration not found
1507 /api/v1/users/{id}/two-factor/request:
1509 summary: Request two factor auth
1510 operationId: requestTwoFactor
1511 description: Request two factor authentication for a user
1515 - $ref: '#/components/parameters/id'
1524 description: Password of the currently authenticated user
1527 description: successful operation
1533 $ref: '#/components/schemas/RequestTwoFactorResponse'
1535 description: invalid password
1537 description: user not found
1539 /api/v1/users/{id}/two-factor/confirm-request:
1541 summary: Confirm two factor auth
1542 operationId: confirmTwoFactorRequest
1543 description: Confirm a two factor authentication request
1547 - $ref: '#/components/parameters/id'
1556 description: Token to identify the two factor request
1559 description: OTP token generated by the app
1565 description: successful operation
1567 description: invalid request token or OTP token
1569 description: user not found
1571 /api/v1/users/{id}/two-factor/disable:
1573 summary: Disable two factor auth
1574 operationId: disableTwoFactor
1575 description: Disable two factor authentication of a user
1579 - $ref: '#/components/parameters/id'
1588 description: Password of the currently authenticated user
1591 description: successful operation
1593 description: invalid password
1595 description: user not found
1599 summary: Get my user information
1600 operationId: getUserInfo
1608 description: successful operation
1614 $ref: '#/components/schemas/User'
1616 summary: Update my user information
1617 operationId: putUserInfo
1625 description: successful operation
1630 $ref: '#/components/schemas/UpdateMe'
1633 /api/v1/users/me/videos/imports:
1635 summary: Get video imports of my user
1643 - $ref: '#/components/parameters/start'
1644 - $ref: '#/components/parameters/count'
1645 - $ref: '#/components/parameters/sort'
1650 description: Filter on import target URL
1654 name: videoChannelSyncId
1657 description: Filter on imports created by a specific channel synchronization
1664 description: Search in video names
1669 description: successful operation
1673 $ref: '#/components/schemas/VideoImportsList'
1675 /api/v1/users/me/video-quota-used:
1677 summary: Get my user used quota
1685 description: successful operation
1693 description: The user video quota used so far in bytes
1694 example: 16810141515
1695 videoQuotaUsedDaily:
1697 description: The user video quota used today in bytes
1700 '/api/v1/users/me/videos/{videoId}/rating':
1702 summary: Get rate of my user for a video
1712 description: The video id
1714 $ref: '#/components/schemas/Video/properties/id'
1717 description: successful operation
1721 $ref: '#/components/schemas/GetMeVideoRating'
1723 /api/v1/users/me/videos:
1725 summary: Get videos of my user
1733 - $ref: '#/components/parameters/start'
1734 - $ref: '#/components/parameters/count'
1735 - $ref: '#/components/parameters/sort'
1738 description: successful operation
1742 $ref: '#/components/schemas/VideoListResponse'
1744 /api/v1/users/me/subscriptions:
1746 summary: Get my user subscriptions
1753 - $ref: '#/components/parameters/start'
1754 - $ref: '#/components/parameters/count'
1755 - $ref: '#/components/parameters/sort'
1758 description: successful operation
1762 $ref: '#/components/schemas/VideoChannelList'
1766 summary: Add subscription to my user
1779 description: uri of the video channels to subscribe to
1785 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1788 description: successful operation
1790 /api/v1/users/me/subscriptions/exist:
1792 summary: Get if subscriptions exist for my user
1799 - $ref: '#/components/parameters/subscriptionsUris'
1802 description: successful operation
1808 /api/v1/users/me/subscriptions/videos:
1810 summary: List videos of subscriptions of my user
1818 - $ref: '#/components/parameters/categoryOneOf'
1819 - $ref: '#/components/parameters/isLive'
1820 - $ref: '#/components/parameters/tagsOneOf'
1821 - $ref: '#/components/parameters/tagsAllOf'
1822 - $ref: '#/components/parameters/licenceOneOf'
1823 - $ref: '#/components/parameters/languageOneOf'
1824 - $ref: '#/components/parameters/nsfw'
1825 - $ref: '#/components/parameters/isLocal'
1826 - $ref: '#/components/parameters/include'
1827 - $ref: '#/components/parameters/privacyOneOf'
1828 - $ref: '#/components/parameters/hasHLSFiles'
1829 - $ref: '#/components/parameters/hasWebtorrentFiles'
1830 - $ref: '#/components/parameters/skipCount'
1831 - $ref: '#/components/parameters/start'
1832 - $ref: '#/components/parameters/count'
1833 - $ref: '#/components/parameters/videosSort'
1836 description: successful operation
1840 $ref: '#/components/schemas/VideoListResponse'
1842 '/api/v1/users/me/subscriptions/{subscriptionHandle}':
1844 summary: Get subscription of my user
1851 - $ref: '#/components/parameters/subscriptionHandle'
1854 description: successful operation
1858 $ref: '#/components/schemas/VideoChannel'
1860 summary: Delete subscription of my user
1867 - $ref: '#/components/parameters/subscriptionHandle'
1870 description: successful operation
1872 /api/v1/users/me/notifications:
1874 summary: List my notifications
1882 description: only list unread notifications
1885 - $ref: '#/components/parameters/start'
1886 - $ref: '#/components/parameters/count'
1887 - $ref: '#/components/parameters/sort'
1890 description: successful operation
1894 $ref: '#/components/schemas/NotificationListResponse'
1896 /api/v1/users/me/notifications/read:
1898 summary: Mark notifications as read by their id
1911 description: ids of the notifications to mark as read
1918 description: successful operation
1920 /api/v1/users/me/notifications/read-all:
1922 summary: Mark all my notification as read
1929 description: successful operation
1931 /api/v1/users/me/notification-settings:
1933 summary: Update my notification settings
1944 newVideoFromSubscription:
1945 $ref: '#/components/schemas/NotificationSettingValue'
1946 newCommentOnMyVideo:
1947 $ref: '#/components/schemas/NotificationSettingValue'
1949 $ref: '#/components/schemas/NotificationSettingValue'
1950 videoAutoBlacklistAsModerator:
1951 $ref: '#/components/schemas/NotificationSettingValue'
1953 $ref: '#/components/schemas/NotificationSettingValue'
1955 $ref: '#/components/schemas/NotificationSettingValue'
1956 myVideoImportFinished:
1957 $ref: '#/components/schemas/NotificationSettingValue'
1959 $ref: '#/components/schemas/NotificationSettingValue'
1960 newUserRegistration:
1961 $ref: '#/components/schemas/NotificationSettingValue'
1963 $ref: '#/components/schemas/NotificationSettingValue'
1964 newInstanceFollower:
1965 $ref: '#/components/schemas/NotificationSettingValue'
1966 autoInstanceFollowing:
1967 $ref: '#/components/schemas/NotificationSettingValue'
1970 description: successful operation
1972 /api/v1/users/me/history/videos:
1974 summary: List watched videos history
1980 - $ref: '#/components/parameters/start'
1981 - $ref: '#/components/parameters/count'
1982 - $ref: '#/components/parameters/search'
1985 description: successful operation
1989 $ref: '#/components/schemas/VideoListResponse'
1991 /api/v1/users/me/history/videos/{videoId}:
1993 summary: Delete history element
2003 $ref: '#/components/schemas/Video/properties/id'
2006 description: successful operation
2008 /api/v1/users/me/history/videos/remove:
2010 summary: Clear video history
2017 multipart/form-data:
2022 description: history before this date will be deleted
2027 description: successful operation
2029 /api/v1/users/me/avatar/pick:
2031 summary: Update my user avatar
2038 description: successful operation
2047 $ref: '#/components/schemas/ActorImage'
2049 description: image file too large
2051 X-File-Maximum-Size:
2055 description: Maximum file size for the avatar
2058 multipart/form-data:
2063 description: The file to upload
2068 contentType: image/png, image/jpeg
2070 /api/v1/users/me/avatar:
2072 summary: Delete my avatar
2079 description: successful operation
2081 /api/v1/users/register:
2083 summary: Register a user
2084 operationId: registerUser
2085 description: Signup has to be enabled and signup approval is not required
2090 description: successful operation
2092 description: request error
2094 description: user registration is not enabled, user limit is reached, registration is not allowed for the ip, requires approval or blocked by a plugin
2096 description: 'a user with this username, channel name or email already exists'
2101 $ref: '#/components/schemas/RegisterUser'
2104 /api/v1/users/registrations/request:
2106 summary: Request registration
2107 description: Signup has to be enabled and require approval on the instance
2108 operationId: requestRegistration
2113 description: successful operation
2117 $ref: '#/components/schemas/UserRegistration'
2119 description: request error or signup approval is not enabled on the instance
2121 description: user registration is not enabled, user limit is reached, registration is not allowed for the ip or blocked by a plugin
2123 description: 'a user or registration with this username, channel name or email already exists'
2128 $ref: '#/components/schemas/UserRegistrationRequest'
2130 /api/v1/users/registrations/{registrationId}/accept:
2136 summary: Accept registration
2137 operationId: acceptRegistration
2141 - $ref: '#/components/parameters/registrationId'
2146 $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
2149 description: successful operation
2151 /api/v1/users/registrations/{registrationId}/reject:
2157 summary: Reject registration
2158 operationId: rejectRegistration
2162 - $ref: '#/components/parameters/registrationId'
2167 $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
2170 description: successful operation
2172 /api/v1/users/registrations/{registrationId}:
2178 summary: Delete registration
2179 description: 'Delete the registration entry. It will not remove the user associated with this registration (if any)'
2180 operationId: deleteRegistration
2184 - $ref: '#/components/parameters/registrationId'
2187 description: successful operation
2189 /api/v1/users/registrations:
2195 summary: List registrations
2196 operationId: listRegistrations
2200 - $ref: '#/components/parameters/start'
2201 - $ref: '#/components/parameters/count'
2219 description: successful operation
2231 $ref: '#/components/schemas/UserRegistration'
2233 /api/v1/videos/ownership:
2235 summary: List video ownership changes
2237 - Video Ownership Change
2242 description: successful operation
2244 '/api/v1/videos/ownership/{id}/accept':
2246 summary: Accept ownership change request
2248 - Video Ownership Change
2252 - $ref: '#/components/parameters/idOrUUID'
2255 description: successful operation
2257 description: cannot terminate an ownership change of another user
2259 description: video ownership change not found
2261 '/api/v1/videos/ownership/{id}/refuse':
2263 summary: Refuse ownership change request
2265 - Video Ownership Change
2269 - $ref: '#/components/parameters/idOrUUID'
2272 description: successful operation
2274 description: cannot terminate an ownership change of another user
2276 description: video ownership change not found
2278 '/api/v1/videos/{id}/give-ownership':
2280 summary: Request ownership change
2282 - Video Ownership Change
2286 - $ref: '#/components/parameters/idOrUUID'
2290 application/x-www-form-urlencoded:
2300 description: successful operation
2302 description: changing video ownership to a remote account is not supported yet
2304 description: video not found
2306 '/api/v1/videos/{id}/token':
2308 summary: Request video token
2309 operationId: requestVideoToken
2310 description: Request special tokens that expire quickly to use them in some context (like accessing private static files)
2316 - $ref: '#/components/parameters/idOrUUID'
2319 description: successful operation
2323 $ref: '#/components/schemas/VideoTokenResponse'
2325 description: incorrect parameters
2327 description: video not found
2329 /api/v1/videos/{id}/studio/edit:
2331 summary: Create a studio task
2335 description: Create a task to edit a video (cut, add intro/outro etc)
2339 - $ref: '#/components/parameters/idOrUUID'
2343 application/x-www-form-urlencoded:
2345 $ref: '#/components/schemas/VideoStudioCreateTask'
2348 description: successful operation
2350 description: incorrect parameters
2352 description: video not found
2356 summary: List videos
2357 operationId: getVideos
2361 - $ref: '#/components/parameters/categoryOneOf'
2362 - $ref: '#/components/parameters/isLive'
2363 - $ref: '#/components/parameters/tagsOneOf'
2364 - $ref: '#/components/parameters/tagsAllOf'
2365 - $ref: '#/components/parameters/licenceOneOf'
2366 - $ref: '#/components/parameters/languageOneOf'
2367 - $ref: '#/components/parameters/nsfw'
2368 - $ref: '#/components/parameters/isLocal'
2369 - $ref: '#/components/parameters/include'
2370 - $ref: '#/components/parameters/privacyOneOf'
2371 - $ref: '#/components/parameters/hasHLSFiles'
2372 - $ref: '#/components/parameters/hasWebtorrentFiles'
2373 - $ref: '#/components/parameters/skipCount'
2374 - $ref: '#/components/parameters/start'
2375 - $ref: '#/components/parameters/count'
2376 - $ref: '#/components/parameters/videosSort'
2379 description: successful operation
2383 $ref: '#/components/schemas/VideoListResponse'
2385 /api/v1/videos/categories:
2387 summary: List available video categories
2388 operationId: getCategories
2393 description: successful operation
2402 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
2404 /api/v1/videos/licences:
2406 summary: List available video licences
2407 operationId: getLicences
2412 description: successful operation
2421 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
2423 /api/v1/videos/languages:
2425 summary: List available video languages
2426 operationId: getLanguages
2431 description: successful operation
2440 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
2442 /api/v1/videos/privacies:
2444 summary: List available video privacy policies
2445 operationId: getPrivacyPolicies
2450 description: successful operation
2459 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
2461 '/api/v1/videos/{id}':
2463 summary: Update a video
2464 operationId: putVideo
2470 - $ref: '#/components/parameters/idOrUUID'
2473 description: successful operation
2476 multipart/form-data:
2481 description: Video thumbnail file
2485 description: Video preview file
2489 $ref: '#/components/schemas/VideoCategorySet'
2491 $ref: '#/components/schemas/VideoLicenceSet'
2493 $ref: '#/components/schemas/VideoLanguageSet'
2495 $ref: '#/components/schemas/VideoPrivacySet'
2497 description: Video description
2500 description: Whether or not we wait transcoding before publish the video
2503 description: A text tell the audience how to support the video creator
2504 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2507 description: Whether or not this video contains sensitive content
2510 description: Video name
2515 description: Video tags (maximum 5 tags each between 2 and 30 characters)
2524 description: Enable or disable comments for this video
2527 description: Enable or disable downloading for this video
2529 originallyPublishedAt:
2530 description: Date when the content was originally published
2534 $ref: '#/components/schemas/VideoScheduledUpdate'
2537 contentType: image/jpeg
2539 contentType: image/jpeg
2541 summary: Get a video
2542 operationId: getVideo
2546 - $ref: '#/components/parameters/idOrUUID'
2549 description: successful operation
2553 $ref: '#/components/schemas/VideoDetails'
2555 summary: Delete a video
2556 operationId: delVideo
2562 - $ref: '#/components/parameters/idOrUUID'
2565 description: successful operation
2567 '/api/v1/videos/{id}/description':
2569 summary: Get complete video description
2570 operationId: getVideoDesc
2574 - $ref: '#/components/parameters/idOrUUID'
2577 description: successful operation
2586 **[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)**
2588 '/api/v1/videos/{id}/source':
2590 summary: Get video source file metadata
2591 operationId: getVideoSource
2595 - $ref: '#/components/parameters/idOrUUID'
2598 description: successful operation
2602 $ref: '#/components/schemas/VideoSource'
2604 '/api/v1/videos/{id}/views':
2606 summary: Notify user is watching a video
2607 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.
2608 operationId: addView
2612 - $ref: '#/components/parameters/idOrUUID'
2617 $ref: '#/components/schemas/UserViewingVideo'
2621 description: successful operation
2623 '/api/v1/videos/{id}/watching':
2625 summary: Set watching progress of a video
2627 description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
2633 - $ref: '#/components/parameters/idOrUUID'
2638 $ref: '#/components/schemas/UserViewingVideo'
2642 description: successful operation
2644 '/api/v1/videos/{id}/stats/overall':
2646 summary: Get overall stats of a video
2652 - $ref: '#/components/parameters/idOrUUID'
2655 description: Filter stats by start date
2661 description: Filter stats by end date
2667 description: successful operation
2671 $ref: '#/components/schemas/VideoStatsOverall'
2673 '/api/v1/videos/{id}/stats/retention':
2675 summary: Get retention stats of a video
2681 - $ref: '#/components/parameters/idOrUUID'
2684 description: successful operation
2688 $ref: '#/components/schemas/VideoStatsRetention'
2690 '/api/v1/videos/{id}/stats/timeseries/{metric}':
2692 summary: Get timeserie stats of a video
2698 - $ref: '#/components/parameters/idOrUUID'
2703 description: The metric to get
2708 - 'aggregateWatchTime'
2711 description: Filter stats by start date
2717 description: Filter stats by end date
2723 description: successful operation
2727 $ref: '#/components/schemas/VideoStatsTimeserie'
2729 /api/v1/videos/upload:
2731 summary: Upload a video
2732 description: Uses a single request to upload a video.
2733 operationId: uploadLegacy
2741 description: successful operation
2745 $ref: '#/components/schemas/VideoUploadResponse'
2747 description: video didn't pass upload filter
2749 description: upload has timed out
2751 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
2753 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
2754 - `quota_reached` for quota limits whether daily or global
2756 X-File-Maximum-Size:
2760 description: Maximum file size for the video
2762 description: video type unsupported
2764 description: video unreadable
2767 multipart/form-data:
2769 $ref: '#/components/schemas/VideoUploadRequestLegacy'
2772 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
2774 contentType: image/jpeg
2776 contentType: image/jpeg
2781 USERNAME="<your_username>"
2782 PASSWORD="<your_password>"
2783 FILE_PATH="<your_file_path>"
2784 CHANNEL_ID="<your_channel_id>"
2786 API="https://peertube2.cpy.re/api/v1"
2789 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
2790 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
2791 token=$(curl -s "$API/users/token" \
2792 --data client_id="$client_id" \
2793 --data client_secret="$client_secret" \
2794 --data grant_type=password \
2795 --data username="$USERNAME" \
2796 --data password="$PASSWORD" \
2797 | jq -r ".access_token")
2800 curl -s "$API/videos/upload" \
2801 -H "Authorization: Bearer $token" \
2803 --form videofile=@"$FILE_PATH" \
2804 --form channelId=$CHANNEL_ID \
2807 /api/v1/videos/upload-resumable:
2809 summary: Initialize the resumable upload of a video
2810 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
2811 operationId: uploadResumableInit
2818 - name: X-Upload-Content-Length
2824 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2825 - name: X-Upload-Content-Type
2832 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2837 $ref: '#/components/schemas/VideoUploadRequestResumable'
2840 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2842 description: created
2848 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2854 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2856 Disambiguate via `type`:
2857 - `max_file_size_reached` for the absolute file size limit
2858 - `quota_reached` for quota limits whether daily or global
2860 description: video type unsupported
2862 summary: Send chunk for the resumable upload of a video
2863 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
2864 operationId: uploadResumable
2875 Created session id to proceed with. If you didn't send chunks in the last hour, it is
2876 not valid anymore and you need to initialize a new upload.
2879 - name: Content-Range
2883 example: bytes 0-262143/2469036
2886 Specifies the bytes in the file that the request is uploading.
2888 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2889 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2890 - name: Content-Length
2897 Size of the chunk that the request is sending.
2899 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2900 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2903 application/octet-stream:
2909 description: last chunk received
2917 $ref: '#/components/schemas/VideoUploadResponse'
2919 description: resume incomplete
2924 example: bytes=0-262143
2930 description: video didn't pass upload filter
2932 description: upload not found
2934 description: chunk doesn't match range
2936 description: video unreadable
2938 description: too many concurrent requests
2940 description: upload is already being processed
2947 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2948 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2949 operationId: uploadResumableCancel
2960 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2961 not valid anymore and the upload session has already been deleted with its data ;-)
2964 - name: Content-Length
2972 description: upload cancelled
2979 description: upload not found
2981 /api/v1/videos/imports:
2983 summary: Import a video
2984 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2985 operationId: importVideo
2993 multipart/form-data:
2995 $ref: '#/components/schemas/VideoCreateImport'
2998 contentType: application/x-bittorrent
3000 contentType: image/jpeg
3002 contentType: image/jpeg
3005 description: successful operation
3009 $ref: '#/components/schemas/VideoUploadResponse'
3011 description: '`magnetUri` or `targetUrl` or a torrent file missing'
3013 description: video didn't pass pre-import filter
3015 description: HTTP or Torrent/magnetURI import not enabled
3017 /api/v1/videos/imports/{id}/cancel:
3019 summary: Cancel video import
3020 description: Cancel a pending video import
3026 - $ref: '#/components/parameters/id'
3029 description: successful operation
3031 /api/v1/videos/imports/{id}:
3033 summary: Delete video import
3034 description: Delete ended video import
3040 - $ref: '#/components/parameters/id'
3043 description: successful operation
3045 /api/v1/videos/live:
3047 summary: Create a live
3048 operationId: addLive
3056 description: successful operation
3060 $ref: '#/components/schemas/VideoUploadResponse'
3062 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
3064 Disambiguate via `type`:
3065 - default type for a validation error
3066 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
3068 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
3070 Disambiguate via `type`:
3071 - `live_not_enabled` for a disabled live feature
3072 - `live_not_allowing_replay` for a disabled replay feature
3073 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
3074 - `max_user_lives_limit_reached` for the user concurrent live limit
3077 multipart/form-data:
3082 description: Channel id that will contain this live video
3087 description: User can stream multiple times in a permanent live
3090 description: User can select live latency mode if enabled by the instance
3091 $ref: '#/components/schemas/LiveVideoLatencyMode'
3093 description: Live video/replay thumbnail file
3097 description: Live video/replay preview file
3101 $ref: '#/components/schemas/VideoPrivacySet'
3103 $ref: '#/components/schemas/VideoCategorySet'
3105 $ref: '#/components/schemas/VideoLicenceSet'
3107 $ref: '#/components/schemas/VideoLanguageSet'
3109 description: Live video/replay description
3112 description: A text tell the audience how to support the creator
3113 example: Please support our work on https://soutenir.framasoft.org/en/ <3
3116 description: Whether or not this live video/replay contains sensitive content
3119 description: Live video/replay name
3124 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
3133 description: Enable or disable comments for this live video/replay
3136 description: Enable or disable downloading for the replay of this live video
3143 contentType: image/jpeg
3145 contentType: image/jpeg
3147 /api/v1/videos/live/{id}:
3149 summary: Get information about a live
3150 operationId: getLiveId
3157 - $ref: '#/components/parameters/idOrUUID'
3160 description: successful operation
3164 $ref: '#/components/schemas/LiveVideoResponse'
3166 summary: Update information about a live
3167 operationId: updateLiveId
3174 - $ref: '#/components/parameters/idOrUUID'
3179 $ref: '#/components/schemas/LiveVideoUpdate'
3182 description: successful operation
3184 description: bad parameters or trying to update a live that has already started
3186 description: trying to save replay of the live but saving replay is not enabled on the instance
3187 /api/v1/videos/live/{id}/sessions:
3189 summary: List live sessions
3190 description: List all sessions created in a particular live
3196 - $ref: '#/components/parameters/idOrUUID'
3199 description: successful operation
3211 $ref: '#/components/schemas/LiveVideoSessionResponse'
3212 /api/v1/videos/{id}/live-session:
3214 summary: Get live session of a replay
3215 description: If the video is a replay of a live, you can find the associated live session using this endpoint
3221 - $ref: '#/components/parameters/idOrUUID'
3224 description: successful operation
3228 $ref: '#/components/schemas/LiveVideoSessionResponse'
3230 /api/v1/users/me/abuses:
3232 summary: List my abuses
3233 operationId: getMyAbuses
3242 description: only list the report with this id
3248 $ref: '#/components/schemas/AbuseStateSet'
3249 - $ref: '#/components/parameters/abusesSort'
3250 - $ref: '#/components/parameters/start'
3251 - $ref: '#/components/parameters/count'
3254 description: successful operation
3266 $ref: '#/components/schemas/Abuse'
3270 summary: List abuses
3271 operationId: getAbuses
3281 description: only list the report with this id
3284 - name: predefinedReason
3286 description: predefined reason the listed reports should contain
3288 $ref: '#/components/schemas/PredefinedAbuseReasons'
3291 description: plain search that will match with video titles, reporter names and more
3297 $ref: '#/components/schemas/AbuseStateSet'
3298 - name: searchReporter
3300 description: only list reports of a specific reporter
3303 - name: searchReportee
3304 description: only list reports of a specific reportee
3310 description: only list reports of a specific video
3313 - name: searchVideoChannel
3315 description: only list reports of a specific video channel
3320 description: only list deleted or blocklisted videos
3328 description: only list account, comment or video reports
3335 - $ref: '#/components/parameters/start'
3336 - $ref: '#/components/parameters/count'
3337 - $ref: '#/components/parameters/abusesSort'
3340 description: successful operation
3352 $ref: '#/components/schemas/Abuse'
3354 summary: Report an abuse
3367 description: Reason why the user reports this video
3372 $ref: '#/components/schemas/PredefinedAbuseReasons'
3377 description: Video id to report
3379 - $ref: '#/components/schemas/Video/properties/id'
3383 description: Timestamp in the video that marks the beginning of the report
3388 description: Timestamp in the video that marks the ending of the report
3394 description: Comment id to report
3396 - $ref: '#/components/schemas/VideoComment/properties/id'
3401 description: Account id to report
3407 description: successful operation
3417 $ref: '#/components/schemas/id'
3419 description: incorrect request parameters
3421 '/api/v1/abuses/{abuseId}':
3423 summary: Update an abuse
3431 - $ref: '#/components/parameters/abuseId'
3439 $ref: '#/components/schemas/AbuseStateSet'
3442 description: Update the report comment visible only to the moderation team
3447 description: successful operation
3449 description: abuse not found
3453 summary: Delete an abuse
3459 - $ref: '#/components/parameters/abuseId'
3462 description: successful operation
3464 description: block not found
3466 '/api/v1/abuses/{abuseId}/messages':
3468 summary: List messages of an abuse
3474 - $ref: '#/components/parameters/abuseId'
3477 description: successful operation
3489 $ref: '#/components/schemas/AbuseMessage'
3491 summary: Add message to an abuse
3497 - $ref: '#/components/parameters/abuseId'
3506 description: Message to send
3514 description: successful operation
3516 description: incorrect request parameters
3518 '/api/v1/abuses/{abuseId}/messages/{abuseMessageId}':
3520 summary: Delete an abuse message
3526 - $ref: '#/components/parameters/abuseId'
3527 - $ref: '#/components/parameters/abuseMessageId'
3530 description: successful operation
3532 '/api/v1/videos/{id}/blacklist':
3534 summary: Block a video
3535 operationId: addVideoBlock
3543 - $ref: '#/components/parameters/idOrUUID'
3546 description: successful operation
3548 summary: Unblock a video by its id
3549 operationId: delVideoBlock
3557 - $ref: '#/components/parameters/idOrUUID'
3560 description: successful operation
3562 description: block not found
3564 /api/v1/videos/blacklist:
3568 summary: List video blocks
3569 operationId: getVideoBlocks
3578 list only blocks that match this type:
3582 - `2`: automatic block that needs review
3590 description: plain search that will match with video titles, and more
3593 - $ref: '#/components/parameters/start'
3594 - $ref: '#/components/parameters/count'
3595 - $ref: '#/components/parameters/blacklistsSort'
3598 description: successful operation
3610 $ref: '#/components/schemas/VideoBlacklist'
3612 /api/v1/videos/{id}/captions:
3614 summary: List captions of a video
3615 operationId: getVideoCaptions
3619 - $ref: '#/components/parameters/idOrUUID'
3622 description: successful operation
3634 $ref: '#/components/schemas/VideoCaption'
3636 /api/v1/videos/{id}/captions/{captionLanguage}:
3638 summary: Add or replace a video caption
3639 operationId: addVideoCaption
3646 - $ref: '#/components/parameters/idOrUUID'
3647 - $ref: '#/components/parameters/captionLanguage'
3650 multipart/form-data:
3655 description: The file to upload.
3660 contentType: text/vtt, application/x-subrip, text/plain
3663 description: successful operation
3665 description: video or language not found
3667 summary: Delete a video caption
3668 operationId: delVideoCaption
3675 - $ref: '#/components/parameters/idOrUUID'
3676 - $ref: '#/components/parameters/captionLanguage'
3679 description: successful operation
3681 description: video or language or caption for that language not found
3683 /api/v1/video-channels:
3685 summary: List video channels
3686 operationId: getVideoChannels
3690 - $ref: '#/components/parameters/start'
3691 - $ref: '#/components/parameters/count'
3692 - $ref: '#/components/parameters/sort'
3695 description: successful operation
3699 $ref: '#/components/schemas/VideoChannelList'
3701 summary: Create a video channel
3702 operationId: addVideoChannel
3709 description: successful operation
3719 $ref: '#/components/schemas/id'
3724 $ref: '#/components/schemas/VideoChannelCreate'
3726 '/api/v1/video-channels/{channelHandle}':
3728 summary: Get a video channel
3729 operationId: getVideoChannel
3733 - $ref: '#/components/parameters/channelHandle'
3736 description: successful operation
3740 $ref: '#/components/schemas/VideoChannel'
3742 summary: Update a video channel
3743 operationId: putVideoChannel
3749 - $ref: '#/components/parameters/channelHandle'
3752 description: successful operation
3757 $ref: '#/components/schemas/VideoChannelUpdate'
3759 summary: Delete a video channel
3760 operationId: delVideoChannel
3766 - $ref: '#/components/parameters/channelHandle'
3769 description: successful operation
3771 '/api/v1/video-channels/{channelHandle}/videos':
3773 summary: List videos of a video channel
3774 operationId: getVideoChannelVideos
3779 - $ref: '#/components/parameters/channelHandle'
3780 - $ref: '#/components/parameters/categoryOneOf'
3781 - $ref: '#/components/parameters/isLive'
3782 - $ref: '#/components/parameters/tagsOneOf'
3783 - $ref: '#/components/parameters/tagsAllOf'
3784 - $ref: '#/components/parameters/licenceOneOf'
3785 - $ref: '#/components/parameters/languageOneOf'
3786 - $ref: '#/components/parameters/nsfw'
3787 - $ref: '#/components/parameters/isLocal'
3788 - $ref: '#/components/parameters/include'
3789 - $ref: '#/components/parameters/privacyOneOf'
3790 - $ref: '#/components/parameters/hasHLSFiles'
3791 - $ref: '#/components/parameters/hasWebtorrentFiles'
3792 - $ref: '#/components/parameters/skipCount'
3793 - $ref: '#/components/parameters/start'
3794 - $ref: '#/components/parameters/count'
3795 - $ref: '#/components/parameters/videosSort'
3798 description: successful operation
3802 $ref: '#/components/schemas/VideoListResponse'
3804 '/api/v1/video-channels/{channelHandle}/video-playlists':
3806 summary: List playlists of a channel
3811 - $ref: '#/components/parameters/channelHandle'
3812 - $ref: '#/components/parameters/start'
3813 - $ref: '#/components/parameters/count'
3814 - $ref: '#/components/parameters/sort'
3815 - $ref: '#/components/parameters/videoPlaylistType'
3818 description: successful operation
3830 $ref: '#/components/schemas/VideoPlaylist'
3832 '/api/v1/video-channels/{channelHandle}/followers':
3836 summary: 'List followers of a video channel'
3839 operationId: getVideoChannelFollowers
3841 - $ref: '#/components/parameters/channelHandle'
3842 - $ref: '#/components/parameters/start'
3843 - $ref: '#/components/parameters/count'
3844 - $ref: '#/components/parameters/followersSort'
3845 - $ref: '#/components/parameters/search'
3848 description: successful operation
3860 $ref: '#/components/schemas/Follow'
3862 '/api/v1/video-channels/{channelHandle}/avatar/pick':
3864 summary: Update channel avatar
3870 - $ref: '#/components/parameters/channelHandle'
3873 description: successful operation
3882 $ref: '#/components/schemas/ActorImage'
3884 description: image file too large
3886 X-File-Maximum-Size:
3890 description: Maximum file size for the avatar
3893 multipart/form-data:
3898 description: The file to upload.
3903 contentType: image/png, image/jpeg
3905 '/api/v1/video-channels/{channelHandle}/avatar':
3907 summary: Delete channel avatar
3913 - $ref: '#/components/parameters/channelHandle'
3916 description: successful operation
3918 '/api/v1/video-channels/{channelHandle}/banner/pick':
3920 summary: Update channel banner
3926 - $ref: '#/components/parameters/channelHandle'
3929 description: successful operation
3938 $ref: '#/components/schemas/ActorImage'
3940 description: image file too large
3942 X-File-Maximum-Size:
3946 description: Maximum file size for the banner
3949 multipart/form-data:
3954 description: The file to upload.
3959 contentType: image/png, image/jpeg
3961 '/api/v1/video-channels/{channelHandle}/banner':
3963 summary: Delete channel banner
3969 - $ref: '#/components/parameters/channelHandle'
3972 description: successful operation
3974 '/api/v1/video-channels/{channelHandle}/import-videos':
3976 summary: Import videos in channel
3977 description: Import a remote channel/playlist videos into a channel
3984 - $ref: '#/components/parameters/channelHandle'
3989 $ref: '#/components/schemas/ImportVideosInChannelCreate'
3992 description: successful operation
3994 '/api/v1/video-channel-syncs':
3996 summary: Create a synchronization for a video channel
3997 operationId: addVideoChannelSync
4006 $ref: '#/components/schemas/VideoChannelSyncCreate'
4009 description: successful operation
4016 $ref: "#/components/schemas/VideoChannelSync"
4018 '/api/v1/video-channel-syncs/{channelSyncId}':
4020 summary: Delete a video channel synchronization
4021 operationId: delVideoChannelSync
4027 - $ref: '#/components/parameters/channelSyncId'
4030 description: successful operation
4032 '/api/v1/video-channel-syncs/{channelSyncId}/sync':
4034 summary: Triggers the channel synchronization job, fetching all the videos from the remote channel
4035 operationId: triggerVideoChannelSync
4041 - $ref: '#/components/parameters/channelSyncId'
4044 description: successful operation
4047 /api/v1/video-playlists/privacies:
4049 summary: List available playlist privacy policies
4050 operationId: getPlaylistPrivacyPolicies
4055 description: successful operation
4064 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
4066 /api/v1/video-playlists:
4068 summary: List video playlists
4069 operationId: getPlaylists
4073 - $ref: '#/components/parameters/start'
4074 - $ref: '#/components/parameters/count'
4075 - $ref: '#/components/parameters/sort'
4076 - $ref: '#/components/parameters/videoPlaylistType'
4079 description: successful operation
4091 $ref: '#/components/schemas/VideoPlaylist'
4093 summary: Create a video playlist
4094 description: If the video playlist is set as public, `videoChannelId` is mandatory.
4095 operationId: addPlaylist
4102 description: successful operation
4112 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4114 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
4116 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
4119 multipart/form-data:
4124 description: Video playlist display name
4129 description: Video playlist thumbnail file
4133 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4135 description: Video playlist description
4141 - $ref: '#/components/schemas/id'
4142 description: Video channel in which the playlist will be published
4147 contentType: image/jpeg
4149 /api/v1/video-playlists/{playlistId}:
4151 summary: Get a video playlist
4155 - $ref: '#/components/parameters/playlistId'
4158 description: successful operation
4162 $ref: '#/components/schemas/VideoPlaylist'
4164 summary: Update a video playlist
4165 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
4172 description: successful operation
4174 - $ref: '#/components/parameters/playlistId'
4177 multipart/form-data:
4182 description: Video playlist display name
4187 description: Video playlist thumbnail file
4191 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4193 description: Video playlist description
4197 - $ref: '#/components/schemas/id'
4198 description: Video channel in which the playlist will be published
4201 contentType: image/jpeg
4203 summary: Delete a video playlist
4209 - $ref: '#/components/parameters/playlistId'
4212 description: successful operation
4214 /api/v1/video-playlists/{playlistId}/videos:
4216 summary: 'List videos of a playlist'
4217 operationId: getVideoPlaylistVideos
4222 - $ref: '#/components/parameters/playlistId'
4223 - $ref: '#/components/parameters/start'
4224 - $ref: '#/components/parameters/count'
4227 description: successful operation
4231 $ref: '#/components/schemas/VideoListResponse'
4233 summary: Add a video in a playlist
4234 operationId: addVideoPlaylistVideo
4241 - $ref: '#/components/parameters/playlistId'
4244 description: successful operation
4250 videoPlaylistElement:
4264 - $ref: '#/components/schemas/Video/properties/uuid'
4265 - $ref: '#/components/schemas/Video/properties/id'
4266 description: Video to add in the playlist
4270 description: Start the video at this specific timestamp
4274 description: Stop the video at this specific timestamp
4278 /api/v1/video-playlists/{playlistId}/videos/reorder:
4280 summary: 'Reorder a playlist'
4281 operationId: reorderVideoPlaylist
4287 - $ref: '#/components/parameters/playlistId'
4290 description: successful operation
4299 description: 'Start position of the element to reorder'
4301 insertAfterPosition:
4303 description: 'New position for the block to reorder, to add the block before the first element'
4307 description: 'How many element from `startPosition` to reorder'
4311 - insertAfterPosition
4313 /api/v1/video-playlists/{playlistId}/videos/{playlistElementId}:
4315 summary: Update a playlist element
4316 operationId: putVideoPlaylistVideo
4322 - $ref: '#/components/parameters/playlistId'
4323 - $ref: '#/components/parameters/playlistElementId'
4326 description: successful operation
4336 description: Start the video at this specific timestamp
4340 description: Stop the video at this specific timestamp
4342 summary: Delete an element from a playlist
4343 operationId: delVideoPlaylistVideo
4349 - $ref: '#/components/parameters/playlistId'
4350 - $ref: '#/components/parameters/playlistElementId'
4353 description: successful operation
4355 '/api/v1/users/me/video-playlists/videos-exist':
4357 summary: Check video exists in my playlists
4366 description: The video ids to check
4370 $ref: '#/components/schemas/Video/properties/id'
4373 description: successful operation
4394 '/api/v1/accounts/{name}/video-playlists':
4396 summary: List playlists of an account
4401 - $ref: '#/components/parameters/name'
4402 - $ref: '#/components/parameters/start'
4403 - $ref: '#/components/parameters/count'
4404 - $ref: '#/components/parameters/sort'
4405 - $ref: '#/components/parameters/search'
4406 - $ref: '#/components/parameters/videoPlaylistType'
4409 description: successful operation
4421 $ref: '#/components/schemas/VideoPlaylist'
4423 '/api/v1/accounts/{name}/video-channels':
4425 summary: List video channels of an account
4430 - $ref: '#/components/parameters/name'
4433 description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
4436 - $ref: '#/components/parameters/start'
4437 - $ref: '#/components/parameters/count'
4438 - $ref: '#/components/parameters/sort'
4441 description: successful operation
4445 $ref: '#/components/schemas/VideoChannelList'
4447 '/api/v1/accounts/{name}/video-channel-syncs':
4449 summary: List the synchronizations of video channels of an account
4455 - $ref: '#/components/parameters/name'
4456 - $ref: '#/components/parameters/start'
4457 - $ref: '#/components/parameters/count'
4458 - $ref: '#/components/parameters/sort'
4461 description: successful operation
4465 $ref: '#/components/schemas/VideoChannelSyncList'
4467 '/api/v1/accounts/{name}/ratings':
4469 summary: List ratings of an account
4475 - $ref: '#/components/parameters/name'
4476 - $ref: '#/components/parameters/start'
4477 - $ref: '#/components/parameters/count'
4478 - $ref: '#/components/parameters/sort'
4482 description: Optionally filter which ratings to retrieve
4490 description: successful operation
4496 $ref: '#/components/schemas/VideoRating'
4498 '/api/v1/videos/{id}/comment-threads':
4500 summary: List threads of a video
4504 - $ref: '#/components/parameters/idOrUUID'
4505 - $ref: '#/components/parameters/start'
4506 - $ref: '#/components/parameters/count'
4507 - $ref: '#/components/parameters/commentsSort'
4510 description: successful operation
4514 $ref: '#/components/schemas/CommentThreadResponse'
4516 summary: Create a thread
4522 - $ref: '#/components/parameters/idOrUUID'
4525 description: successful operation
4529 $ref: '#/components/schemas/CommentThreadPostResponse'
4531 description: video does not exist
4540 - $ref: '#/components/schemas/VideoComment/properties/text'
4546 '/api/v1/videos/{id}/comment-threads/{threadId}':
4548 summary: Get a thread
4552 - $ref: '#/components/parameters/idOrUUID'
4553 - $ref: '#/components/parameters/threadId'
4556 description: successful operation
4560 $ref: '#/components/schemas/VideoCommentThreadTree'
4562 '/api/v1/videos/{id}/comments/{commentId}':
4564 summary: Reply to a thread of a video
4570 - $ref: '#/components/parameters/idOrUUID'
4571 - $ref: '#/components/parameters/commentId'
4574 description: successful operation
4578 $ref: '#/components/schemas/CommentThreadPostResponse'
4580 description: thread or video does not exist
4589 - $ref: '#/components/schemas/VideoComment/properties/text'
4595 summary: Delete a comment or a reply
4601 - $ref: '#/components/parameters/idOrUUID'
4602 - $ref: '#/components/parameters/commentId'
4605 description: successful operation
4607 description: cannot remove comment of another user
4609 description: comment or video does not exist
4611 description: comment is already deleted
4613 '/api/v1/videos/{id}/rate':
4615 summary: Like/dislike a video
4621 - $ref: '#/components/parameters/idOrUUID'
4637 description: successful operation
4639 description: video does not exist
4641 '/api/v1/videos/{id}/hls':
4643 summary: Delete video HLS files
4649 operationId: delVideoHLS
4651 - $ref: '#/components/parameters/idOrUUID'
4654 description: successful operation
4656 description: video does not exist
4657 '/api/v1/videos/{id}/webtorrent':
4659 summary: Delete video WebTorrent files
4665 operationId: delVideoWebTorrent
4667 - $ref: '#/components/parameters/idOrUUID'
4670 description: successful operation
4672 description: video does not exist
4674 '/api/v1/videos/{id}/transcoding':
4676 summary: Create a transcoding job
4682 operationId: createVideoTranscoding
4684 - $ref: '#/components/parameters/idOrUUID'
4700 description: successful operation
4702 description: video does not exist
4704 /api/v1/search/videos:
4708 summary: Search videos
4709 operationId: searchVideos
4714 allowEmptyValue: false
4716 String to search. If the user can make a remote URI search, and the string is an URI then the
4717 PeerTube instance will fetch the remote object and add it to its database. Then,
4718 you can use the REST API to fetch the complete video information and interact with it.
4721 - $ref: '#/components/parameters/categoryOneOf'
4722 - $ref: '#/components/parameters/isLive'
4723 - $ref: '#/components/parameters/tagsOneOf'
4724 - $ref: '#/components/parameters/tagsAllOf'
4725 - $ref: '#/components/parameters/licenceOneOf'
4726 - $ref: '#/components/parameters/languageOneOf'
4727 - $ref: '#/components/parameters/nsfw'
4728 - $ref: '#/components/parameters/isLocal'
4729 - $ref: '#/components/parameters/include'
4730 - $ref: '#/components/parameters/privacyOneOf'
4731 - $ref: '#/components/parameters/uuids'
4732 - $ref: '#/components/parameters/hasHLSFiles'
4733 - $ref: '#/components/parameters/hasWebtorrentFiles'
4734 - $ref: '#/components/parameters/skipCount'
4735 - $ref: '#/components/parameters/start'
4736 - $ref: '#/components/parameters/count'
4737 - $ref: '#/components/parameters/searchTarget'
4738 - $ref: '#/components/parameters/videosSearchSort'
4741 description: Get videos that are published after this date
4747 description: Get videos that are published before this date
4751 - name: originallyPublishedStartDate
4753 description: Get videos that are originally published after this date
4757 - name: originallyPublishedEndDate
4759 description: Get videos that are originally published before this date
4765 description: Get videos that have this minimum duration
4770 description: Get videos that have this maximum duration
4774 'searchTarget === search-index':
4775 $ref: '#/components/callbacks/searchIndex'
4778 description: successful operation
4782 $ref: '#/components/schemas/VideoListResponse'
4784 description: search index unavailable
4786 /api/v1/search/video-channels:
4790 summary: Search channels
4791 operationId: searchChannels
4797 String to search. If the user can make a remote URI search, and the string is an URI then the
4798 PeerTube instance will fetch the remote object and add it to its database. Then,
4799 you can use the REST API to fetch the complete channel information and interact with it.
4802 - $ref: '#/components/parameters/start'
4803 - $ref: '#/components/parameters/count'
4804 - $ref: '#/components/parameters/searchTarget'
4805 - $ref: '#/components/parameters/sort'
4807 'searchTarget === search-index':
4808 $ref: '#/components/callbacks/searchIndex'
4811 description: successful operation
4815 $ref: '#/components/schemas/VideoChannelList'
4817 description: search index unavailable
4819 /api/v1/search/video-playlists:
4823 summary: Search playlists
4824 operationId: searchPlaylists
4830 String to search. If the user can make a remote URI search, and the string is an URI then the
4831 PeerTube instance will fetch the remote object and add it to its database. Then,
4832 you can use the REST API to fetch the complete playlist information and interact with it.
4835 - $ref: '#/components/parameters/start'
4836 - $ref: '#/components/parameters/count'
4837 - $ref: '#/components/parameters/searchTarget'
4838 - $ref: '#/components/parameters/sort'
4840 'searchTarget === search-index':
4841 $ref: '#/components/callbacks/searchIndex'
4844 description: successful operation
4856 $ref: '#/components/schemas/VideoPlaylist'
4858 description: search index unavailable
4860 /api/v1/blocklist/status:
4865 summary: Get block status of accounts/hosts
4870 description: 'Check if these accounts are blocked'
4871 example: [ 'goofy@example.com', 'donald@example.com' ]
4879 description: 'Check if these hosts are blocked'
4880 example: [ 'example.com' ]
4887 description: successful operation
4891 $ref: '#/components/schemas/BlockStatus'
4893 /api/v1/server/blocklist/accounts:
4897 summary: List account blocks
4902 - $ref: '#/components/parameters/start'
4903 - $ref: '#/components/parameters/count'
4904 - $ref: '#/components/parameters/sort'
4907 description: successful operation
4911 summary: Block an account
4923 example: chocobozzz@example.org
4924 description: account to block, in the form `username@domain`
4929 description: successful operation
4931 description: self-blocking forbidden
4933 '/api/v1/server/blocklist/accounts/{accountName}':
4937 summary: Unblock an account by its handle
4945 description: account to unblock, in the form `username@domain`
4950 description: successful operation
4952 description: account or account block does not exist
4954 /api/v1/server/blocklist/servers:
4958 summary: List server blocks
4963 - $ref: '#/components/parameters/start'
4964 - $ref: '#/components/parameters/count'
4965 - $ref: '#/components/parameters/sort'
4968 description: successful operation
4972 summary: Block a server
4985 description: server domain to block
4990 description: successful operation
4992 description: self-blocking forbidden
4994 '/api/v1/server/blocklist/servers/{host}':
4998 summary: Unblock a server by its domain
5006 description: server domain to unblock
5012 description: successful operation
5014 description: account block does not exist
5016 /api/v1/server/redundancy/{host}:
5019 - Instance Redundancy
5020 summary: Update a server redundancy policy
5028 description: server domain to mirror
5040 description: allow mirroring of the host's local videos
5045 description: successful operation
5047 description: server is not already known
5049 /api/v1/server/redundancy/videos:
5053 summary: List videos being mirrored
5054 operationId: getMirroredVideos
5062 description: direction of the mirror
5068 - $ref: '#/components/parameters/start'
5069 - $ref: '#/components/parameters/count'
5070 - $ref: '#/components/parameters/videoRedundanciesSort'
5073 description: successful operation
5079 $ref: '#/components/schemas/VideoRedundancy'
5083 summary: Mirror a video
5084 operationId: putMirroredVideo
5095 $ref: '#/components/schemas/Video/properties/id'
5100 description: successful operation
5102 description: cannot mirror a local video
5104 description: video does not exist
5106 description: video is already mirrored
5108 /api/v1/server/redundancy/videos/{redundancyId}:
5112 summary: Delete a mirror done on a video
5113 operationId: delMirroredVideo
5118 - name: redundancyId
5121 description: id of an existing redundancy on a video
5126 description: successful operation
5128 description: video redundancy not found
5130 /api/v1/server/stats:
5134 summary: Get instance stats
5135 description: Get instance public statistics. This endpoint is cached.
5136 operationId: getInstanceStats
5139 description: successful operation
5143 $ref: '#/components/schemas/ServerStats'
5145 /api/v1/server/logs/client:
5149 summary: Send client log
5150 operationId: sendClientLog
5155 $ref: '#/components/schemas/SendClientLog'
5158 description: successful operation
5160 /api/v1/server/logs:
5164 summary: Get instance logs
5165 operationId: getInstanceLogs
5171 description: successful operation
5179 /api/v1/server/audit-logs:
5183 summary: Get instance audit logs
5184 operationId: getInstanceAuditLogs
5190 description: successful operation
5202 summary: List plugins
5203 operationId: getPlugins
5216 - $ref: '#/components/parameters/start'
5217 - $ref: '#/components/parameters/count'
5218 - $ref: '#/components/parameters/sort'
5221 description: successful operation
5225 $ref: '#/components/schemas/PluginResponse'
5227 /api/v1/plugins/available:
5231 summary: List available plugins
5232 operationId: getAvailablePlugins
5245 - name: currentPeerTubeEngine
5249 - $ref: '#/components/parameters/start'
5250 - $ref: '#/components/parameters/count'
5251 - $ref: '#/components/parameters/sort'
5254 description: successful operation
5258 $ref: '#/components/schemas/PluginResponse'
5260 description: plugin index unavailable
5262 /api/v1/plugins/install:
5266 summary: Install a plugin
5267 operationId: addPlugin
5280 example: peertube-plugin-auth-ldap
5283 additionalProperties: false
5290 additionalProperties: false
5293 description: successful operation
5295 description: should have either `npmName` or `path` set
5297 /api/v1/plugins/update:
5301 summary: Update a plugin
5302 operationId: updatePlugin
5315 example: peertube-plugin-auth-ldap
5318 additionalProperties: false
5325 additionalProperties: false
5328 description: successful operation
5330 description: should have either `npmName` or `path` set
5332 description: existing plugin not found
5334 /api/v1/plugins/uninstall:
5338 summary: Uninstall a plugin
5339 operationId: uninstallPlugin
5351 description: name of the plugin/theme in its package.json
5352 example: peertube-plugin-auth-ldap
5357 description: successful operation
5359 description: existing plugin not found
5361 /api/v1/plugins/{npmName}:
5365 summary: Get a plugin
5366 operationId: getPlugin
5371 - $ref: '#/components/parameters/npmName'
5374 description: successful operation
5378 $ref: '#/components/schemas/Plugin'
5380 description: plugin not found
5382 /api/v1/plugins/{npmName}/settings:
5386 summary: Set a plugin's settings
5391 - $ref: '#/components/parameters/npmName'
5400 additionalProperties: true
5403 description: successful operation
5405 description: plugin not found
5407 /api/v1/plugins/{npmName}/public-settings:
5411 summary: Get a plugin's public settings
5413 - $ref: '#/components/parameters/npmName'
5416 description: successful operation
5421 additionalProperties: true
5423 description: plugin not found
5425 /api/v1/plugins/{npmName}/registered-settings:
5429 summary: Get a plugin's registered settings
5434 - $ref: '#/components/parameters/npmName'
5437 description: successful operation
5442 additionalProperties: true
5444 description: plugin not found
5446 /api/v1/metrics/playback:
5448 summary: Create playback metrics
5449 description: These metrics are exposed by OpenTelemetry metrics exporter if enabled.
5456 $ref: '#/components/schemas/PlaybackMetricCreate'
5459 description: successful operation
5462 - url: 'https://peertube2.cpy.re'
5463 description: Live Test Server (live data - latest nightly version)
5464 - url: 'https://peertube3.cpy.re'
5465 description: Live Test Server (live data - latest RC version)
5466 - url: 'https://peertube.cpy.re'
5467 description: Live Test Server (live data - stable version)
5474 description: Offset used to paginate results
5482 description: "Number of items to return"
5492 description: Sort column
5500 description: Plain text search, applied to various parts of the model depending on endpoint
5508 If the administrator enabled search index support, you can override the default search target.
5511 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
5512 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
5513 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
5514 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
5515 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
5516 * 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
5517 the data from the origin instance API
5540 Sort videos by criteria (prefixing with `-` means `DESC` order):
5541 * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
5542 * `best` - Same than `hot`, but also takes into account user video history
5543 * `trending` - Sort videos by recent views ("recent" is defined by the admin)
5544 * `views` - Sort videos using their `views` counter
5545 * `publishedAt` - Sort by video publication date (when it became publicly available)
5551 Sort videos by criteria (prefixing with `-` means `DESC` order):
5566 description: Sort comments by criteria
5576 description: Sort blocklists by criteria
5592 description: Plain text search that will match with user usernames or emails
5599 description: Filter results down to (un)banned users
5606 description: Sort users by criteria
5617 description: Sort abuses by criteria
5624 videoRedundanciesSort:
5628 description: Sort abuses by criteria
5637 description: Sort followers by criteria
5647 description: The username or handle of the account
5650 example: chocobozzz | chocobozzz@example.org
5655 description: Entity id
5657 $ref: '#/components/schemas/id'
5659 name: registrationId
5662 description: Registration ID
5664 $ref: '#/components/schemas/id'
5669 description: The object id, uuid or short uuid
5672 - $ref: '#/components/schemas/id'
5673 - $ref: '#/components/schemas/UUIDv4'
5674 - $ref: '#/components/schemas/shortUUID'
5679 description: Playlist id
5681 $ref: '#/components/schemas/VideoPlaylist/properties/id'
5683 name: playlistElementId
5686 description: Playlist element id
5688 $ref: '#/components/schemas/id'
5693 description: Abuse id
5695 $ref: '#/components/schemas/Abuse/properties/id'
5697 name: abuseMessageId
5700 description: Abuse message id
5702 $ref: '#/components/schemas/AbuseMessage/properties/id'
5704 name: captionLanguage
5707 description: The caption language
5709 $ref: '#/components/schemas/VideoLanguageSet'
5714 description: The video channel handle
5717 example: my_username | my_username@example.com
5722 description: Channel Sync id
5724 $ref: '#/components/schemas/Abuse/properties/id'
5726 name: subscriptionHandle
5729 description: The subscription handle
5732 example: my_username | my_username@example.com
5737 description: The thread id (root comment id)
5744 description: The comment id
5746 $ref: '#/components/schemas/VideoComment/properties/id'
5751 description: whether or not the video is a live
5758 description: category id of the video (see [/videos/categories](#operation/getCategories))
5761 - $ref: '#/components/schemas/VideoCategorySet'
5764 $ref: '#/components/schemas/VideoCategorySet'
5771 description: tag(s) of the video
5785 description: tag(s) of the video, where all should be present in the video
5798 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
5801 - $ref: '#/components/schemas/VideoLanguageSet'
5804 $ref: '#/components/schemas/VideoLanguageSet'
5811 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5814 - $ref: '#/components/schemas/VideoLicenceSet'
5817 $ref: '#/components/schemas/VideoLicenceSet'
5824 description: if you don't need the `total` in the response
5835 description: whether to include nsfw videos, if any
5847 description: '**PeerTube >= 4.0** Display only local or remote videos'
5854 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
5856 name: hasWebtorrentFiles
5861 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
5867 $ref: '#/components/schemas/VideoPrivacySet'
5868 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
5876 description: 'Find videos with specific UUIDs'
5890 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
5894 - `1` NOT_PUBLISHED_STATE
5905 description: list of uris to check if each is part of the user subscriptions
5915 description: name of the plugin/theme on npmjs.com or in its package.json
5918 example: peertube-plugin-auth-ldap
5923 description: job type
5927 - activitypub-follow
5928 - activitypub-http-broadcast
5929 - activitypub-http-fetcher
5930 - activitypub-http-unicast
5935 - videos-views-stats
5936 - activitypub-refresher
5939 - video-channel-import
5963 description: Filename
5967 name: videoFileToken
5970 description: Video file token [generated](#operation/requestVideoToken) by PeerTube so you don't need to provide an OAuth token in the request header.
5973 reinjectVideoFileToken:
5974 name: reinjectVideoFileToken
5977 description: Ask the server to reinject videoFileToken in URLs in m3u8 playlist
5985 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5990 Authenticating via OAuth requires the following steps:
5991 - Have an activated account
5992 - [Generate] an access token for that account at `/api/v1/users/token`.
5993 - Make requests with the *Authorization: Bearer <token\>* header
5994 - Profit, depending on the role assigned to the account
5996 Note that the __access token is valid for 1 day__ and is given
5997 along with a __refresh token valid for 2 weeks__.
5999 [Generate]: https://docs.joinpeertube.org/api/rest-getting-started
6003 tokenUrl: /api/v1/users/token
6006 moderator: Moderator scope
6009 # Reusable core properties
6017 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
6018 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
6023 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
6024 example: 2y84q2MQUMWPbiEcxNXMgC
6027 description: immutable name of the user, used to find or mention its actor
6029 pattern: '/^[a-z0-9._]+$/'
6034 description: immutable name of the channel, used to interact with its actor
6035 example: framasoft_videos
6036 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
6047 description: category id of the video (see [/videos/categories](#operation/getCategories))
6049 VideoConstantNumber-Category:
6052 $ref: '#/components/schemas/VideoCategorySet'
6055 example: Science & Technology
6059 description: licence id of the video (see [/videos/licences](#operation/getLicences))
6061 VideoConstantNumber-Licence:
6064 $ref: '#/components/schemas/VideoLicenceSet'
6067 example: Attribution - Share Alike
6071 description: language id of the video (see [/videos/languages](#operation/getLanguages))
6073 VideoConstantString-Language:
6076 $ref: '#/components/schemas/VideoLanguageSet'
6081 VideoPlaylistPrivacySet:
6087 description: Video playlist privacy policy (see [/video-playlists/privacies])
6088 VideoPlaylistPrivacyConstant:
6091 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
6095 VideoPlaylistTypeSet:
6100 description: The video playlist type (Regular = `1`, Watch Later = `2`)
6101 VideoPlaylistTypeConstant:
6104 $ref: '#/components/schemas/VideoPlaylistTypeSet'
6115 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
6116 VideoPrivacyConstant:
6119 $ref: '#/components/schemas/VideoPrivacySet'
6127 additionalProperties:
6128 x-additionalPropertiesName: account
6137 additionalProperties:
6138 x-additionalPropertiesName: host
6159 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
6166 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
6169 LiveVideoLatencyMode:
6175 description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
6196 - `4`: Waiting for live stream
6198 - `6`: To move to an external storage (object storage...)
6199 - `7`: Transcoding failed
6200 - `8`: Moving to an external storage failed
6201 - `9`: To edit using studio edition feature
6211 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
6215 $ref: '#/components/schemas/AbuseStateSet'
6218 AbusePredefinedReasons:
6231 example: [spamOrMisleading]
6236 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
6238 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
6240 VideoResolutionConstant:
6241 description: resolutions and their labels for the video
6244 $ref: '#/components/schemas/VideoResolutionSet'
6248 VideoScheduledUpdate:
6251 $ref: '#/components/schemas/VideoPrivacySet'
6255 description: When to update the video
6275 $ref: '#/components/schemas/ActorImage'
6276 VideoChannelSummary:
6279 $ref: '#/components/schemas/id'
6293 $ref: '#/components/schemas/ActorImage'
6307 - $ref: '#/components/schemas/Video'
6312 $ref: '#/components/schemas/id'
6316 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
6317 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6319 $ref: '#/components/schemas/VideoResolutionConstant'
6322 description: Video file size in bytes
6325 description: Direct URL of the torrent file
6329 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
6333 description: Direct URL of the video
6337 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
6341 description: Frames per second of the video file
6345 description: URL dereferencing the output of ffprobe on the file
6346 VideoStreamingPlaylists:
6351 $ref: '#/components/schemas/id'
6359 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
6360 VideoStreamingPlaylists-HLS:
6371 Video files associated to this playlist.
6373 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
6375 $ref: '#/components/schemas/VideoFile'
6387 $ref: '#/components/schemas/Video/properties/id'
6389 $ref: '#/components/schemas/Video/properties/uuid'
6391 $ref: '#/components/schemas/Video/properties/name'
6395 description: object id for the video
6397 - $ref: '#/components/schemas/id'
6399 description: universal identifier for the video, that can be used across instances
6401 - $ref: '#/components/schemas/UUIDv4'
6404 - $ref: '#/components/schemas/shortUUID'
6410 example: 2017-10-01T10:52:46.396Z
6411 description: time at which the video object was first drafted
6415 example: 2018-10-01T10:52:46.396Z
6416 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
6420 example: 2021-05-04T08:01:01.502Z
6421 description: last time the video's metadata was modified
6422 originallyPublishedAt:
6425 example: 2010-10-01T10:52:46.396Z
6426 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
6429 - $ref: '#/components/schemas/VideoConstantNumber-Category'
6430 description: category in which the video is classified
6433 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
6434 description: licence under which the video is distributed
6437 - $ref: '#/components/schemas/VideoConstantString-Language'
6438 description: main language used in the video
6441 - $ref: '#/components/schemas/VideoPrivacyConstant'
6442 description: privacy policy used to distribute the video
6446 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
6447 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
6451 truncated description of the video, written in Markdown.
6452 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
6457 description: duration of the video in seconds
6462 description: title of the video
6463 example: What is PeerTube?
6468 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
6471 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
6474 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
6491 - $ref: '#/components/schemas/VideoStateConstant'
6492 description: represents the internal state of the video processing within the PeerTube instance
6496 - $ref: '#/components/schemas/VideoScheduledUpdate'
6504 $ref: '#/components/schemas/AccountSummary'
6506 $ref: '#/components/schemas/VideoChannelSummary'
6515 - $ref: '#/components/schemas/Video'
6520 description: If the video is a live, you have the amount of current viewers
6523 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
6524 description: path at which to get the full description of maximum `10000` characters
6527 description: A text tell the audience how to support the video creator
6528 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6532 $ref: '#/components/schemas/VideoChannel'
6534 $ref: '#/components/schemas/Account'
6536 example: [flowers, gardening]
6554 - https://peertube2.cpy.re/tracker/announce
6555 - wss://peertube2.cpy.re/tracker/socket
6559 $ref: '#/components/schemas/VideoFile'
6561 WebTorrent/raw video files. If WebTorrent is disabled on the server:
6563 - field will be empty
6564 - video files will be found in `streamingPlaylists[].files` field
6568 $ref: '#/components/schemas/VideoStreamingPlaylists'
6570 HLS playlists/manifest files. If HLS is disabled on the server:
6572 - field will be empty
6573 - video files will be found in `files` field
6574 FileRedundancyInformation:
6577 $ref: '#/components/schemas/id'
6602 $ref: '#/components/schemas/id'
6609 $ref: '#/components/schemas/UUIDv4'
6616 $ref: '#/components/schemas/FileRedundancyInformation'
6620 $ref: '#/components/schemas/FileRedundancyInformation'
6621 VideoImportStateConstant:
6629 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
6636 additionalProperties: false
6640 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
6641 required: [targetUrl]
6644 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6645 required: [magnetUri]
6648 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
6649 required: [torrentfile]
6650 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6659 - $ref: '#/components/schemas/id'
6663 description: remote URL where to find the import's source video
6664 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
6668 description: magnet URI allowing to resolve the import's source video
6669 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6674 description: Torrent file containing only the video file
6681 - $ref: '#/components/schemas/VideoImportStateConstant'
6697 - $ref: '#/components/schemas/Video'
6707 $ref: '#/components/schemas/VideoImport'
6711 $ref: '#/components/schemas/id'
6714 example: The video is a spam
6718 $ref: '#/components/schemas/AbusePredefinedReasons'
6720 $ref: '#/components/schemas/Account'
6722 $ref: '#/components/schemas/AbuseStateConstant'
6725 example: Decided to ban the server since it spams us regularly
6729 $ref: '#/components/schemas/VideoInfo'
6736 $ref: '#/components/schemas/id'
6747 $ref: '#/components/schemas/AccountSummary'
6751 $ref: '#/components/schemas/id'
6753 $ref: '#/components/schemas/Video/properties/id'
6765 $ref: '#/components/schemas/UUIDv4'
6783 $ref: '#/components/schemas/id'
6785 $ref: '#/components/schemas/UUIDv4'
6788 - $ref: '#/components/schemas/shortUUID'
6811 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
6813 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
6815 $ref: '#/components/schemas/AccountSummary'
6817 $ref: '#/components/schemas/VideoChannelSummary'
6821 $ref: '#/components/schemas/id'
6828 description: Text of the comment
6830 example: This video is wonderful!
6832 $ref: '#/components/schemas/id'
6836 - $ref: '#/components/schemas/id'
6838 $ref: '#/components/schemas/Video/properties/id'
6853 totalRepliesFromVideoAuthor:
6860 $ref: '#/components/schemas/Account'
6861 VideoCommentThreadTree:
6864 $ref: '#/components/schemas/VideoComment'
6868 $ref: '#/components/schemas/VideoCommentThreadTree'
6872 $ref: '#/components/schemas/VideoConstantString-Language'
6894 $ref: '#/components/schemas/id'
6905 $ref: '#/components/schemas/ActorImage'
6909 $ref: '#/components/schemas/id'
6914 description: immutable name of the actor, used to find or mention it
6916 - $ref: '#/components/schemas/username'
6920 description: server on which the actor is resident
6921 hostRedundancyAllowed:
6923 description: whether this actor's host allows redundancy of its videos
6927 description: number of actors subscribed to by this actor, as seen by this instance
6931 description: number of followers of this actor, as seen by this instance
6940 - $ref: '#/components/schemas/Actor'
6943 description: object id for the user tied to this account
6945 - $ref: '#/components/schemas/User/properties/id'
6948 description: editable name of the account, displayed in its representations
6953 description: text or bio displayed on the account's profile
6961 description: timestamp within the video, in seconds
6968 Event since last viewing call:
6969 * `seek` - If the user seeked the video
6992 VideoStatsRetention:
7004 VideoStatsTimeserie:
7081 allowedForCurrentIP:
7083 requiresEmailVerification:
7101 $ref: '#/components/schemas/VideoResolutionSet'
7118 videoChannelSynchronization:
7191 example: 16810141515
7232 description: URL of the current user page
7239 description: Stack trace of the error if there is one
7242 description: User agent of the web browser that sends the message
7245 description: Additional information regarding this log
7255 totalDailyActiveUsers:
7257 totalWeeklyActiveUsers:
7259 totalMonthlyActiveUsers:
7263 totalLocalVideoViews:
7265 description: Total video views made on the instance
7266 totalLocalVideoComments:
7268 description: Total comments made by local users
7269 totalLocalVideoFilesSize:
7275 totalLocalVideoChannels:
7277 totalLocalDailyActiveVideoChannels:
7279 totalLocalWeeklyActiveVideoChannels:
7281 totalLocalMonthlyActiveVideoChannels:
7283 totalLocalPlaylists:
7285 totalInstanceFollowers:
7287 totalInstanceFollowing:
7304 totalActivityPubMessagesProcessed:
7306 totalActivityPubMessagesSuccesses:
7308 totalActivityPubMessagesErrors:
7311 activityPubMessagesProcessedPerSecond:
7313 totalActivityPubMessagesWaiting:
7390 requiresEmailVerification:
7405 description: Settings that apply to new users, if registration is enabled
7409 example: 16810141515
7415 description: Settings pertaining to transcoding jobs
7419 allowAdditionalExtensions:
7421 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
7424 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
7427 description: Amount of threads used by ffmpeg for 1 transcoding job
7430 description: Amount of transcoding jobs to execute in parallel
7436 New profiles can be added by plugins ; available in core PeerTube: 'default'.
7439 description: Resolutions to transcode _new videos_ to
7461 description: WebTorrent-specific settings
7467 description: HLS-specific settings
7487 video_channel_synchronization:
7522 $ref: '#/components/schemas/id'
7524 $ref: '#/components/schemas/Actor'
7526 $ref: '#/components/schemas/Actor'
7529 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
7542 PredefinedAbuseReasons:
7543 description: Reason categories that help triage reports
7561 $ref: '#/components/schemas/id'
7573 - activitypub-http-unicast
7574 - activitypub-http-broadcast
7575 - activitypub-http-fetcher
7576 - activitypub-follow
7581 - videos-views-stats
7582 - activitypub-refresher
7584 - video-channel-import
7587 additionalProperties: true
7590 additionalProperties: true
7606 $ref: '#/components/schemas/id'
7611 $ref: '#/components/schemas/id'
7612 VideoUploadRequestCommon:
7615 description: Video name
7617 example: What is PeerTube?
7621 description: Channel id that will contain this video
7626 $ref: '#/components/schemas/VideoPrivacySet'
7628 $ref: '#/components/schemas/VideoCategorySet'
7630 $ref: '#/components/schemas/VideoLicenceSet'
7632 $ref: '#/components/schemas/VideoLanguageSet'
7634 description: Video description
7637 **[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)**
7639 description: Whether or not we wait transcoding before publish the video
7642 description: A text tell the audience how to support the video creator
7643 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7646 description: Whether or not this video contains sensitive content
7649 description: Video tags (maximum 5 tags each between 2 and 30 characters)
7662 description: Enable or disable comments for this video
7665 description: Enable or disable downloading for this video
7667 originallyPublishedAt:
7668 description: Date when the content was originally published
7672 $ref: '#/components/schemas/VideoScheduledUpdate'
7674 description: Video thumbnail file
7678 description: Video preview file
7684 VideoUploadRequestLegacy:
7686 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7692 description: Video file
7695 VideoUploadRequestResumable:
7697 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7703 description: Video filename including extension
7706 example: what_is_peertube.mp4
7708 description: Video thumbnail file
7712 description: Video preview file
7715 VideoUploadResponse:
7721 $ref: '#/components/schemas/Video/properties/id'
7723 $ref: '#/components/schemas/Video/properties/uuid'
7725 $ref: '#/components/schemas/Video/properties/shortUUID'
7726 CommentThreadResponse:
7735 $ref: '#/components/schemas/VideoComment'
7736 CommentThreadPostResponse:
7739 $ref: '#/components/schemas/VideoComment'
7759 $ref: '#/components/schemas/Video'
7763 $ref: '#/components/schemas/Account'
7766 description: Automatically start playing the upcoming video after the currently playing video
7767 autoPlayNextVideoPlaylist:
7769 description: Automatically start playing the video on the playlist after the currently playing video
7772 description: Automatically start playing the video on the watch page
7782 description: The user email
7785 description: Has the user confirmed their email address?
7788 - $ref: '#/components/schemas/id'
7792 description: Auth plugin to use to authenticate the user
7796 noInstanceConfigWarningModal:
7798 noAccountSetupWarningModal:
7803 $ref: '#/components/schemas/NSFWPolicy'
7808 $ref: '#/components/schemas/UserRole'
7817 description: Theme enabled by this user
7819 $ref: '#/components/schemas/username'
7823 $ref: '#/components/schemas/VideoChannel'
7826 description: The user video quota in bytes
7830 description: The user daily video quota in bytes
7834 description: Enable P2P in the player
7837 - $ref: '#/components/schemas/User'
7839 # optionally present fields: they require WITH_STATS scope
7842 description: Count of videos published
7845 description: Count of reports/abuses of which the user is a target
7846 abusesAcceptedCount:
7848 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
7851 description: Count of reports/abuses created by the user
7854 description: Count of comments published
7858 $ref: '#/components/schemas/username'
7860 $ref: '#/components/schemas/password'
7864 description: The user email
7867 description: The user video quota in bytes
7871 description: The user daily video quota in bytes
7874 $ref: '#/components/schemas/usernameChannel'
7876 $ref: '#/components/schemas/UserRole'
7878 $ref: '#/components/schemas/UserAdminFlags'
7889 description: The updated email of the user
7891 - $ref: '#/components/schemas/User/properties/email'
7894 description: Set the email as verified
7897 description: The updated video quota of the user in bytes
7900 description: The updated daily video quota of the user in bytes
7904 description: The auth plugin to use to authenticate the user
7905 example: 'peertube-plugin-auth-saml2'
7907 $ref: '#/components/schemas/UserRole'
7909 $ref: '#/components/schemas/UserAdminFlags'
7911 $ref: '#/components/schemas/password'
7913 # see shared/models/users/user-update-me.model.ts:
7916 $ref: '#/components/schemas/password'
7918 $ref: '#/components/schemas/password'
7920 description: new email used for login and service communications
7922 - $ref: '#/components/schemas/User/properties/email'
7925 description: new name of the user in its representations
7930 description: new NSFW display policy
7937 description: whether to enable P2P in the player or not
7940 description: new preference regarding playing videos automatically
7943 description: new preference regarding playing following videos automatically
7944 autoPlayNextVideoPlaylist:
7946 description: new preference regarding playing following playlist videos automatically
7947 videosHistoryEnabled:
7949 description: whether to keep track of watched history or not
7954 description: list of languages to filter videos down to
7957 noInstanceConfigWarningModal:
7959 noAccountSetupWarningModal:
7966 $ref: '#/components/schemas/id'
7973 description: Rating of the video
7980 $ref: '#/components/schemas/Video'
7987 description: Rating of the video
7995 description: immutable name of the user, used to find or mention its actor
7997 - $ref: '#/components/schemas/username'
7999 $ref: '#/components/schemas/password'
8003 description: email of the user, used for login or service communications
8006 description: editable name of the user, displayed in its representations
8011 description: channel base information used to create the first channel of the user
8014 $ref: '#/components/schemas/usernameChannel'
8022 UserRegistrationRequest:
8024 - $ref: '#/components/schemas/RegisterUser'
8029 description: reason for the user to register on the instance
8031 - registrationReason
8033 UserRegistrationAcceptOrReject:
8038 description: Moderation response to send to the user
8039 preventEmailDelivery:
8041 description: Set it to true if you don't want PeerTube to send an email to the user
8043 - moderationResponse
8048 $ref: '#/components/schemas/id'
8058 description: 'The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
8088 description: If the registration has been accepted, this is a partial user object created by the registration
8091 $ref: '#/components/schemas/id'
8097 pattern: /^[a-z0-9]$/
8100 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
8103 pattern: /^[a-zA-Z0-9]$/
8106 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
8107 OAuthToken-password:
8109 - $ref: '#/components/schemas/OAuthClient'
8119 $ref: '#/components/schemas/User/properties/username'
8121 $ref: '#/components/schemas/password'
8128 OAuthToken-refresh_token:
8130 - $ref: '#/components/schemas/OAuthClient'
8141 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
8150 - $ref: '#/components/schemas/Actor'
8155 description: editable name of the channel, displayed in its representations
8156 example: Videos of Framasoft
8161 example: Videos made with <3 by Framasoft
8166 description: text shown by default on all videos of this channel, to tell the audience how to support it
8167 example: Please support our work on https://soutenir.framasoft.org/en/ <3
8180 $ref: '#/components/schemas/ActorImage'
8189 $ref: '#/components/schemas/UUIDv4'
8194 description: Channel display name
8196 description: Channel description
8198 description: How to support/fund the channel
8202 - $ref: '#/components/schemas/VideoChannelEdit'
8205 description: username of the channel to create
8207 - $ref: '#/components/schemas/usernameChannel'
8213 - $ref: '#/components/schemas/VideoChannelEdit'
8215 bulkVideosSupportUpdate:
8217 description: Update the support field for all videos of this channel
8228 - $ref: '#/components/schemas/VideoChannel'
8229 - $ref: '#/components/schemas/Actor'
8231 ImportVideosInChannelCreate:
8236 example: https://youtube.com/c/UC_myfancychannel
8239 description: If part of a channel sync process, specify its id to assign video imports to this channel synchronization
8241 - 'externalChannelUrl'
8247 $ref: '#/components/schemas/id'
8259 example: 'https://youtube.com/c/UC_myfancychannel'
8268 $ref: '#/components/schemas/VideoChannel'
8269 VideoChannelSyncList:
8279 - $ref: '#/components/schemas/VideoChannelSync'
8280 VideoChannelSyncCreate:
8285 example: https://youtube.com/c/UC_myfancychannel
8287 $ref: '#/components/schemas/id'
8291 name: 'media:peerLink'
8300 - application/x-bittorrent
8306 name: 'media:content'
8337 VideoCommentsForXML:
8372 description: video watch page URL
8375 description: video canonical URL
8379 description: video publication date
8382 description: video description
8385 description: video description
8388 description: publisher user name
8391 description: video category (MRSS)
8394 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
8409 description: video embed path, relative to the canonical URL domain (MRSS)
8418 description: video watch path, relative to the canonical URL domain (MRSS)
8439 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
8440 'media:description':
8447 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
8450 description: main streamable file for the video
8460 - application/x-bittorrent
8469 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)
8472 - $ref: '#/components/schemas/MRSSPeerLink'
8473 - $ref: '#/components/schemas/MRSSGroupContent'
8474 NotificationSettingValue:
8477 Notification type. One of the following values, or a sum of multiple values:
8487 $ref: '#/components/schemas/id'
8491 Notification type, following the `UserNotificationType` enum:
8493 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
8495 - `2` NEW_COMMENT_ON_MY_VIDEO
8497 - `3` NEW_ABUSE_FOR_MODERATORS
8499 - `4` BLACKLIST_ON_MY_VIDEO
8501 - `5` UNBLACKLIST_ON_MY_VIDEO
8503 - `6` MY_VIDEO_PUBLISHED
8505 - `7` MY_VIDEO_IMPORT_SUCCESS
8507 - `8` MY_VIDEO_IMPORT_ERROR
8509 - `9` NEW_USER_REGISTRATION
8513 - `11` COMMENT_MENTION
8515 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
8517 - `13` NEW_INSTANCE_FOLLOWER
8519 - `14` AUTO_INSTANCE_FOLLOWING
8521 - `15` ABUSE_STATE_CHANGE
8523 - `16` ABUSE_NEW_MESSAGE
8525 - `17` NEW_PLUGIN_VERSION
8527 - `18` NEW_PEERTUBE_VERSION
8533 - $ref: '#/components/schemas/VideoInfo'
8537 $ref: '#/components/schemas/ActorInfo'
8543 $ref: '#/components/schemas/id'
8546 $ref: '#/components/schemas/VideoInfo'
8551 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
8561 $ref: '#/components/schemas/id'
8565 $ref: '#/components/schemas/VideoInfo'
8567 $ref: '#/components/schemas/ActorInfo'
8573 $ref: '#/components/schemas/id'
8576 - $ref: '#/components/schemas/VideoInfo'
8582 $ref: '#/components/schemas/id'
8585 - $ref: '#/components/schemas/VideoInfo'
8589 - $ref: '#/components/schemas/ActorInfo'
8595 $ref: '#/components/schemas/id'
8597 $ref: '#/components/schemas/ActorInfo'
8625 NotificationListResponse:
8634 $ref: '#/components/schemas/Notification'
8639 example: peertube-plugin-auth-ldap
8667 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
8670 additionalProperties: true
8686 $ref: '#/components/schemas/Plugin'
8693 description: User can stream multiple times in a permanent live
8696 description: User can select live latency mode if enabled by the instance
8697 $ref: '#/components/schemas/LiveVideoLatencyMode'
8703 description: Included in the response if an appropriate token is provided
8706 description: Included in the response if an appropriate token is provided
8709 description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
8713 description: User can stream multiple times in a permanent live
8716 description: User can select live latency mode if enabled by the instance
8717 $ref: '#/components/schemas/LiveVideoLatencyMode'
8719 RequestTwoFactorResponse:
8726 description: The token to send to confirm this request
8729 description: The OTP secret
8732 description: The OTP URI
8734 VideoStudioCreateTask:
8782 title: add-watermark
8796 LiveVideoSessionResponse:
8803 description: Start date of the live session
8808 description: End date of the live session
8819 Error type if an error occurred during the live session:
8820 - `1`: Bad socket health (transcoding is too slow)
8821 - `2`: Max duration exceeded
8822 - `3`: Quota exceeded
8823 - `4`: Quota FFmpeg error
8824 - `5`: Video has been blacklisted during the live
8827 description: Video replay information
8832 $ref: '#/components/schemas/UUIDv4'
8834 $ref: '#/components/schemas/shortUUID'
8836 PlaybackMetricCreate:
8841 - 'p2p-media-loader'
8845 description: Current player video resolution
8848 description: Current player video fps
8851 description: How many resolution changes occured since the last metric creation
8854 description: How many errors occured since the last metric creation
8857 description: How many bytes were downloaded with P2P since the last metric creation
8858 downloadedBytesHTTP:
8860 description: How many bytes were downloaded with HTTP since the last metric creation
8863 description: How many bytes were uploaded with P2P since the last metric creation
8866 - $ref: '#/components/schemas/id'
8867 - $ref: '#/components/schemas/UUIDv4'
8868 - $ref: '#/components/schemas/shortUUID'
8873 - downloadedBytesP2P
8874 - downloadedBytesHTTP
8880 'https://search.example.org/api/v1/search/videos':
8882 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
8885 description: successful operation
8889 $ref: '#/components/schemas/VideoListResponse'