]> git.immae.eu Git - github/Chocobozzz/PeerTube.git/blame_incremental - support/doc/api/openapi.yaml
projects / github / Chocobozzz / PeerTube.git / blame_incremental
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (non-incremental) | history | HEAD
Bumped to version v5.2.1
[github/Chocobozzz/PeerTube.git] / support / doc / api / openapi.yaml
... / ...
CommitLineData
1openapi: 3.0.0
2info:
3 title: PeerTube
4 version: 5.1.0
5 contact:
6 name: PeerTube Community
7 url: https://joinpeertube.org
8 license:
9 name: AGPLv3.0
10 url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
11 x-logo:
12 url: https://joinpeertube.org/img/brand.png
13 altText: PeerTube Project Homepage
14 description: |
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:
19
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)
23
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.
26
27 # Authentication
28
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__.
32
33 ## Roles
34
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.
37
38 # Errors
39
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.
42
43 ```
44 HTTP 1.1 404 Not Found
45 Content-Type: application/problem+json; charset=utf-8
46
47 {
48 "detail": "Video not found",
49 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
50 "status": 404,
51 "title": "Not Found",
52 "type": "about:blank"
53 }
54 ```
55
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
58 and are non-obvious:
59
60 ```
61 HTTP 1.1 403 Forbidden
62 Content-Type: application/problem+json; charset=utf-8
63
64 {
65 "detail": "Cannot get this video regarding follow constraints",
66 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
67 "status": 403,
68 "title": "Forbidden",
69 "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
70 }
71 ```
72
73 Here a 403 error could otherwise mean that the video is private or blocklisted.
74
75 ### Validation errors
76
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:
80
81 ```
82 HTTP 1.1 400 Bad Request
83 Content-Type: application/problem+json; charset=utf-8
84
85 {
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",
89 "invalid-params": {
90 "id": {
91 "location": "params",
92 "msg": "Invalid value",
93 "param": "id",
94 "value": "9c9de5e8-0a1e-484a-b099-e80766180"
95 }
96 },
97 "status": 400,
98 "title": "Bad Request",
99 "type": "about:blank"
100 }
101 ```
102
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`
106 is about.
107
108 ### Deprecated error fields
109
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)
113
114 # Rate limits
115
116 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
117
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 |
124
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.
127
128 You can get details about the current state of your rate limit by reading the
129 following headers:
130
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 |
137
138 # CORS
139
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:
142
143 | Endpoint |
144 |------------------------- ---|
145 | `/api/*` |
146 | `/download/*` |
147 | `/lazy-static/*` |
148 | `/.well-known/webfinger` |
149
150 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
151externalDocs:
152 url: https://docs.joinpeertube.org/api-rest-reference.html
153tags:
154 - name: Register
155 description: |
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.
159 - name: Session
160 x-displayName: Login/Logout
161 description: |
162 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
163 - name: Accounts
164 description: >
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
167 are also Actors.
168
169 When a comment is posted, it is done with your Account's Actor.
170 - name: Users
171 description: >
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.
175 - name: My User
176 description: >
177 Operations related to your own User, when logged-in.
178 - name: My Subscriptions
179 description: >
180 Operations related to your subscriptions to video channels, their
181 new videos, and how to keep up to date with their latest publications!
182 - name: My History
183 description: >
184 Operations related to your watch history.
185 - name: My Notifications
186 description: >
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.
191 - name: Config
192 description: >
193 Each server exposes public information regarding supported videos and
194 options.
195 - name: Job
196 description: >
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
200 description: >
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
205 endpoints.
206 externalDocs:
207 url: https://docs.joinpeertube.org/admin/following-instances#instances-follows
208 - name: Instance Redundancy
209 description: >
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).
214 externalDocs:
215 url: https://docs.joinpeertube.org/admin/following-instances#instances-redundancy
216 - name: Plugins
217 description: >
218 Managing plugins installed from a local path or from NPM, or search for new ones.
219 externalDocs:
220 url: https://docs.joinpeertube.org/api/plugins
221 - name: Abuses
222 description: |
223 Abuses deal with reports of local or remote videos/comments/accounts alike.
224 - name: Video
225 description: |
226 Operations dealing with listing, uploading, fetching or modifying videos.
227 - name: Video Upload
228 description: |
229 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
230
231 ### Upload
232
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
235
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.
239
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
245
246 ### Import
247
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
251
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
263 description: >
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.
267 - name: Video Blocks
268 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
269 - name: Video Rates
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.
273 - name: Video Files
274 description: Operations on video files
275 - name: Video Transcoding
276 description: Video transcoding related operations
277 - name: Video Stats
278 description: Video statistics
279 - name: Video Feeds
280 description: Server syndication feeds of videos
281 - name: Search
282 description: |
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
286 the advanced search.
287
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.
290 - name: Homepage
291 description: Get and update the custom homepage
292 - name: Video Mirroring
293 description: |
294 PeerTube instances can mirror videos from one another, and help distribute some videos.
295
296 For importing videos as your own, refer to [video imports](#operation/importVideo).
297 - name: Stats
298 description: |
299 Statistics
300 - name: Runner Registration Token
301 description: |
302 Manage runner registration token
303
304x-tagGroups:
305 - name: Static endpoints
306 tags:
307 - Static Video Files
308 - name: Feeds
309 tags:
310 - Video Feeds
311 - name: Auth
312 tags:
313 - Register
314 - Session
315 - name: Accounts
316 tags:
317 - Accounts
318 - Users
319 - My User
320 - My Subscriptions
321 - My Notifications
322 - My History
323 - name: Videos
324 tags:
325 - Video
326 - Video Upload
327 - Video Imports
328 - Video Captions
329 - Video Channels
330 - Video Comments
331 - Video Rates
332 - Video Playlists
333 - Video Stats
334 - Video Ownership Change
335 - Video Mirroring
336 - Video Files
337 - Video Transcoding
338 - Live Videos
339 - Channels Sync
340 - name: Search
341 tags:
342 - Search
343 - name: Moderation
344 tags:
345 - Abuses
346 - Video Blocks
347 - Account Blocks
348 - Server Blocks
349 - name: Instance
350 tags:
351 - Config
352 - Homepage
353 - Instance Follows
354 - Instance Redundancy
355 - Plugins
356 - Stats
357 - Logs
358 - Job
359 - name: Remote Jobs
360 tags:
361 - Runner Registration Token
362 - Runner Jobs
363 - Runners
364
365paths:
366 '/static/webseed/{filename}':
367 get:
368 tags:
369 - Static Video Files
370 summary: Get public WebTorrent video file
371 parameters:
372 - $ref: '#/components/parameters/staticFilename'
373 responses:
374 '200':
375 description: successful operation
376 '404':
377 description: not found
378 '/static/webseed/private/{filename}':
379 get:
380 tags:
381 - Static Video Files
382 summary: Get private WebTorrent video file
383 parameters:
384 - $ref: '#/components/parameters/staticFilename'
385 - $ref: '#/components/parameters/videoFileToken'
386 security:
387 - OAuth2: []
388 responses:
389 '200':
390 description: successful operation
391 '403':
392 description: invalid auth
393 '404':
394 description: not found
395
396 '/static/streaming-playlists/hls/{filename}':
397 get:
398 tags:
399 - Static Video Files
400 summary: Get public HLS video file
401 parameters:
402 - $ref: '#/components/parameters/staticFilename'
403 security:
404 - OAuth2: []
405 responses:
406 '200':
407 description: successful operation
408 '403':
409 description: invalid auth
410 '404':
411 description: not found
412 '/static/streaming-playlists/hls/private/{filename}':
413 get:
414 tags:
415 - Static Video Files
416 summary: Get private HLS video file
417 parameters:
418 - $ref: '#/components/parameters/staticFilename'
419 - $ref: '#/components/parameters/videoFileToken'
420 - $ref: '#/components/parameters/reinjectVideoFileToken'
421 security:
422 - OAuth2: []
423 responses:
424 '200':
425 description: successful operation
426 '403':
427 description: invalid auth
428 '404':
429 description: not found
430
431
432 '/feeds/video-comments.{format}':
433 get:
434 tags:
435 - Video Feeds
436 summary: Comments on videos feeds
437 operationId: getSyndicatedComments
438 parameters:
439 - name: format
440 in: path
441 required: true
442 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
443 schema:
444 type: string
445 enum:
446 - xml
447 - rss
448 - rss2
449 - atom
450 - atom1
451 - json
452 - json1
453 - name: videoId
454 in: query
455 description: 'limit listing to a specific video'
456 schema:
457 type: string
458 - name: accountId
459 in: query
460 description: 'limit listing to a specific account'
461 schema:
462 type: string
463 - name: accountName
464 in: query
465 description: 'limit listing to a specific account'
466 schema:
467 type: string
468 - name: videoChannelId
469 in: query
470 description: 'limit listing to a specific video channel'
471 schema:
472 type: string
473 - name: videoChannelName
474 in: query
475 description: 'limit listing to a specific video channel'
476 schema:
477 type: string
478 responses:
479 '200':
480 description: successful operation
481 headers:
482 Cache-Control:
483 schema:
484 type: string
485 default: 'max-age=900' # 15 min cache
486 content:
487 application/xml:
488 schema:
489 $ref: '#/components/schemas/VideoCommentsForXML'
490 examples:
491 nightly:
492 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
493 application/rss+xml:
494 schema:
495 $ref: '#/components/schemas/VideoCommentsForXML'
496 examples:
497 nightly:
498 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
499 text/xml:
500 schema:
501 $ref: '#/components/schemas/VideoCommentsForXML'
502 examples:
503 nightly:
504 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
505 application/atom+xml:
506 schema:
507 $ref: '#/components/schemas/VideoCommentsForXML'
508 examples:
509 nightly:
510 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
511 application/json:
512 schema:
513 type: object
514 examples:
515 nightly:
516 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
517 '400':
518 x-summary: field inconsistencies
519 description: >
520 Arises when:
521 - videoId filter is mixed with a channel filter
522 '404':
523 description: video, video channel or account not found
524 '406':
525 description: accept header unsupported
526
527 '/feeds/videos.{format}':
528 get:
529 tags:
530 - Video Feeds
531 summary: Common videos feeds
532 operationId: getSyndicatedVideos
533 parameters:
534 - name: format
535 in: path
536 required: true
537 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
538 schema:
539 type: string
540 enum:
541 - xml
542 - rss
543 - rss2
544 - atom
545 - atom1
546 - json
547 - json1
548 - name: accountId
549 in: query
550 description: 'limit listing to a specific account'
551 schema:
552 type: string
553 - name: accountName
554 in: query
555 description: 'limit listing to a specific account'
556 schema:
557 type: string
558 - name: videoChannelId
559 in: query
560 description: 'limit listing to a specific video channel'
561 schema:
562 type: string
563 - name: videoChannelName
564 in: query
565 description: 'limit listing to a specific video channel'
566 schema:
567 type: string
568 - $ref: '#/components/parameters/sort'
569 - $ref: '#/components/parameters/nsfw'
570 - $ref: '#/components/parameters/isLocal'
571 - $ref: '#/components/parameters/include'
572 - $ref: '#/components/parameters/privacyOneOf'
573 - $ref: '#/components/parameters/hasHLSFiles'
574 - $ref: '#/components/parameters/hasWebtorrentFiles'
575 responses:
576 '200':
577 description: successful operation
578 headers:
579 Cache-Control:
580 schema:
581 type: string
582 default: 'max-age=900' # 15 min cache
583 content:
584 application/xml:
585 schema:
586 $ref: '#/components/schemas/VideosForXML'
587 examples:
588 nightly:
589 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
590 application/rss+xml:
591 schema:
592 $ref: '#/components/schemas/VideosForXML'
593 examples:
594 nightly:
595 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
596 text/xml:
597 schema:
598 $ref: '#/components/schemas/VideosForXML'
599 examples:
600 nightly:
601 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
602 application/atom+xml:
603 schema:
604 $ref: '#/components/schemas/VideosForXML'
605 examples:
606 nightly:
607 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
608 application/json:
609 schema:
610 type: object
611 examples:
612 nightly:
613 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
614 '404':
615 description: video channel or account not found
616 '406':
617 description: accept header unsupported
618
619 '/feeds/subscriptions.{format}':
620 get:
621 tags:
622 - Video Feeds
623 summary: Videos of subscriptions feeds
624 operationId: getSyndicatedSubscriptionVideos
625 parameters:
626 - name: format
627 in: path
628 required: true
629 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
630 schema:
631 type: string
632 enum:
633 - xml
634 - rss
635 - rss2
636 - atom
637 - atom1
638 - json
639 - json1
640 - name: accountId
641 in: query
642 description: limit listing to a specific account
643 schema:
644 type: string
645 required: true
646 - name: token
647 in: query
648 description: private token allowing access
649 schema:
650 type: string
651 required: true
652 - $ref: '#/components/parameters/sort'
653 - $ref: '#/components/parameters/nsfw'
654 - $ref: '#/components/parameters/isLocal'
655 - $ref: '#/components/parameters/include'
656 - $ref: '#/components/parameters/privacyOneOf'
657 - $ref: '#/components/parameters/hasHLSFiles'
658 - $ref: '#/components/parameters/hasWebtorrentFiles'
659 responses:
660 '200':
661 description: successful operation
662 headers:
663 Cache-Control:
664 schema:
665 type: string
666 default: 'max-age=900' # 15 min cache
667 content:
668 application/xml:
669 schema:
670 $ref: '#/components/schemas/VideosForXML'
671 application/rss+xml:
672 schema:
673 $ref: '#/components/schemas/VideosForXML'
674 text/xml:
675 schema:
676 $ref: '#/components/schemas/VideosForXML'
677 application/atom+xml:
678 schema:
679 $ref: '#/components/schemas/VideosForXML'
680 application/json:
681 schema:
682 type: object
683 '406':
684 description: accept header unsupported
685
686 '/feeds/podcast/videos.xml':
687 get:
688 tags:
689 - Video Feeds
690 summary: Videos podcast feed
691 operationId: getVideosPodcastFeed
692 parameters:
693 - name: videoChannelId
694 in: query
695 description: 'Limit listing to a specific video channel'
696 required: true
697 schema:
698 type: string
699 responses:
700 '200':
701 description: successful operation
702 headers:
703 Cache-Control:
704 schema:
705 type: string
706 default: 'max-age=900' # 15 min cache
707 '404':
708 description: video channel not found
709
710 '/api/v1/accounts/{name}':
711 get:
712 tags:
713 - Accounts
714 summary: Get an account
715 operationId: getAccount
716 parameters:
717 - $ref: '#/components/parameters/name'
718 responses:
719 '200':
720 description: successful operation
721 content:
722 application/json:
723 schema:
724 $ref: '#/components/schemas/Account'
725 '404':
726 description: account not found
727
728 '/api/v1/accounts/{name}/videos':
729 get:
730 tags:
731 - Accounts
732 - Video
733 summary: 'List videos of an account'
734 operationId: getAccountVideos
735 parameters:
736 - $ref: '#/components/parameters/name'
737 - $ref: '#/components/parameters/categoryOneOf'
738 - $ref: '#/components/parameters/isLive'
739 - $ref: '#/components/parameters/tagsOneOf'
740 - $ref: '#/components/parameters/tagsAllOf'
741 - $ref: '#/components/parameters/licenceOneOf'
742 - $ref: '#/components/parameters/languageOneOf'
743 - $ref: '#/components/parameters/nsfw'
744 - $ref: '#/components/parameters/isLocal'
745 - $ref: '#/components/parameters/include'
746 - $ref: '#/components/parameters/privacyOneOf'
747 - $ref: '#/components/parameters/hasHLSFiles'
748 - $ref: '#/components/parameters/hasWebtorrentFiles'
749 - $ref: '#/components/parameters/skipCount'
750 - $ref: '#/components/parameters/start'
751 - $ref: '#/components/parameters/count'
752 - $ref: '#/components/parameters/videosSort'
753 - $ref: '#/components/parameters/excludeAlreadyWatched'
754 responses:
755 '200':
756 description: successful operation
757 content:
758 application/json:
759 schema:
760 $ref: '#/components/schemas/VideoListResponse'
761 x-codeSamples:
762 - lang: JavaScript
763 source: |
764 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
765 .then(function(response) {
766 return response.json()
767 }).then(function(data) {
768 console.log(data)
769 })
770 - lang: Shell
771 source: |
772 ## DEPENDENCIES: jq
773 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
774 - lang: Ruby
775 source: |
776 require 'net/http'
777 require 'json'
778
779 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
780
781 http = Net::HTTP.new(uri.host, uri.port)
782 http.use_ssl = true
783
784 response = http.get(uri.request_uri)
785
786 puts JSON.parse(response.read_body)
787 - lang: Python
788 source: |
789 import requests
790
791 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
792 json = r.json()
793
794 print(json)
795
796 '/api/v1/accounts/{name}/followers':
797 get:
798 tags:
799 - Accounts
800 summary: 'List followers of an account'
801 security:
802 - OAuth2: []
803 operationId: getAccountFollowers
804 parameters:
805 - $ref: '#/components/parameters/name'
806 - $ref: '#/components/parameters/start'
807 - $ref: '#/components/parameters/count'
808 - $ref: '#/components/parameters/followersSort'
809 - $ref: '#/components/parameters/search'
810 responses:
811 '200':
812 description: successful operation
813 content:
814 application/json:
815 schema:
816 type: object
817 properties:
818 total:
819 type: integer
820 example: 1
821 data:
822 type: array
823 items:
824 $ref: '#/components/schemas/Follow'
825
826 /api/v1/accounts:
827 get:
828 tags:
829 - Accounts
830 summary: List accounts
831 operationId: getAccounts
832 parameters:
833 - $ref: '#/components/parameters/start'
834 - $ref: '#/components/parameters/count'
835 - $ref: '#/components/parameters/sort'
836 responses:
837 '200':
838 description: successful operation
839 content:
840 'application/json':
841 schema:
842 type: object
843 properties:
844 total:
845 type: integer
846 example: 1
847 data:
848 type: array
849 items:
850 $ref: '#/components/schemas/Account'
851
852 /api/v1/config:
853 get:
854 tags:
855 - Config
856 summary: Get instance public configuration
857 operationId: getConfig
858 responses:
859 '200':
860 description: successful operation
861 content:
862 application/json:
863 schema:
864 $ref: '#/components/schemas/ServerConfig'
865 examples:
866 nightly:
867 externalValue: https://peertube2.cpy.re/api/v1/config
868
869 /api/v1/config/about:
870 get:
871 summary: Get instance "About" information
872 operationId: getAbout
873 tags:
874 - Config
875 responses:
876 '200':
877 description: successful operation
878 content:
879 application/json:
880 schema:
881 $ref: '#/components/schemas/ServerConfigAbout'
882 examples:
883 nightly:
884 externalValue: https://peertube2.cpy.re/api/v1/config/about
885
886 /api/v1/config/custom:
887 get:
888 summary: Get instance runtime configuration
889 operationId: getCustomConfig
890 tags:
891 - Config
892 security:
893 - OAuth2:
894 - admin
895 responses:
896 '200':
897 description: successful operation
898 content:
899 application/json:
900 schema:
901 $ref: '#/components/schemas/ServerConfigCustom'
902 put:
903 summary: Set instance runtime configuration
904 operationId: putCustomConfig
905 tags:
906 - Config
907 security:
908 - OAuth2:
909 - admin
910 responses:
911 '200':
912 description: successful operation
913 '400':
914 x-summary: field inconsistencies
915 description: >
916 Arises when:
917 - the emailer is disabled and the instance is open to registrations
918 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
919 delete:
920 summary: Delete instance runtime configuration
921 operationId: delCustomConfig
922 tags:
923 - Config
924 security:
925 - OAuth2:
926 - admin
927 responses:
928 '200':
929 description: successful operation
930
931 /api/v1/custom-pages/homepage/instance:
932 get:
933 summary: Get instance custom homepage
934 tags:
935 - Homepage
936 responses:
937 '404':
938 description: No homepage set
939 '200':
940 description: successful operation
941 content:
942 application/json:
943 schema:
944 $ref: '#/components/schemas/CustomHomepage'
945 put:
946 summary: Set instance custom homepage
947 tags:
948 - Homepage
949 security:
950 - OAuth2:
951 - admin
952 requestBody:
953 content:
954 application/json:
955 schema:
956 type: object
957 properties:
958 content:
959 type: string
960 description: content of the homepage, that will be injected in the client
961 responses:
962 '204':
963 description: successful operation
964
965 /api/v1/jobs/pause:
966 post:
967 summary: Pause job queue
968 security:
969 - OAuth2:
970 - admin
971 tags:
972 - Job
973 responses:
974 '204':
975 description: successful operation
976
977 /api/v1/jobs/resume:
978 post:
979 summary: Resume job queue
980 security:
981 - OAuth2:
982 - admin
983 tags:
984 - Job
985 responses:
986 '204':
987 description: successful operation
988
989 /api/v1/jobs/{state}:
990 get:
991 summary: List instance jobs
992 operationId: getJobs
993 security:
994 - OAuth2:
995 - admin
996 tags:
997 - Job
998 parameters:
999 - name: state
1000 in: path
1001 required: true
1002 description: The state of the job ('' for for no filter)
1003 schema:
1004 type: string
1005 enum:
1006 - ''
1007 - active
1008 - completed
1009 - failed
1010 - waiting
1011 - delayed
1012 - $ref: '#/components/parameters/jobType'
1013 - $ref: '#/components/parameters/start'
1014 - $ref: '#/components/parameters/count'
1015 - $ref: '#/components/parameters/sort'
1016 responses:
1017 '200':
1018 description: successful operation
1019 content:
1020 application/json:
1021 schema:
1022 type: object
1023 properties:
1024 total:
1025 type: integer
1026 example: 1
1027 data:
1028 type: array
1029 maxItems: 100
1030 items:
1031 $ref: '#/components/schemas/Job'
1032
1033 /api/v1/server/followers:
1034 get:
1035 tags:
1036 - Instance Follows
1037 summary: List instances following the server
1038 parameters:
1039 - $ref: '#/components/parameters/followState'
1040 - $ref: '#/components/parameters/actorType'
1041 - $ref: '#/components/parameters/start'
1042 - $ref: '#/components/parameters/count'
1043 - $ref: '#/components/parameters/sort'
1044 responses:
1045 '200':
1046 description: successful operation
1047 content:
1048 application/json:
1049 schema:
1050 type: object
1051 properties:
1052 total:
1053 type: integer
1054 example: 1
1055 data:
1056 type: array
1057 items:
1058 $ref: '#/components/schemas/Follow'
1059
1060 '/api/v1/server/followers/{nameWithHost}':
1061 delete:
1062 summary: Remove or reject a follower to your server
1063 security:
1064 - OAuth2:
1065 - admin
1066 tags:
1067 - Instance Follows
1068 parameters:
1069 - name: nameWithHost
1070 in: path
1071 required: true
1072 description: The remote actor handle to remove from your followers
1073 schema:
1074 type: string
1075 format: email
1076 responses:
1077 '204':
1078 description: successful operation
1079 '404':
1080 description: follower not found
1081
1082 '/api/v1/server/followers/{nameWithHost}/reject':
1083 post:
1084 summary: Reject a pending follower to your server
1085 security:
1086 - OAuth2:
1087 - admin
1088 tags:
1089 - Instance Follows
1090 parameters:
1091 - name: nameWithHost
1092 in: path
1093 required: true
1094 description: The remote actor handle to remove from your followers
1095 schema:
1096 type: string
1097 format: email
1098 responses:
1099 '204':
1100 description: successful operation
1101 '404':
1102 description: follower not found
1103
1104 '/api/v1/server/followers/{nameWithHost}/accept':
1105 post:
1106 summary: Accept a pending follower to your server
1107 security:
1108 - OAuth2:
1109 - admin
1110 tags:
1111 - Instance Follows
1112 parameters:
1113 - name: nameWithHost
1114 in: path
1115 required: true
1116 description: The remote actor handle to remove from your followers
1117 schema:
1118 type: string
1119 format: email
1120 responses:
1121 '204':
1122 description: successful operation
1123 '404':
1124 description: follower not found
1125
1126 /api/v1/server/following:
1127 get:
1128 tags:
1129 - Instance Follows
1130 summary: List instances followed by the server
1131 parameters:
1132 - $ref: '#/components/parameters/followState'
1133 - $ref: '#/components/parameters/actorType'
1134 - $ref: '#/components/parameters/start'
1135 - $ref: '#/components/parameters/count'
1136 - $ref: '#/components/parameters/sort'
1137 responses:
1138 '200':
1139 description: successful operation
1140 content:
1141 application/json:
1142 schema:
1143 type: object
1144 properties:
1145 total:
1146 type: integer
1147 example: 1
1148 data:
1149 type: array
1150 items:
1151 $ref: '#/components/schemas/Follow'
1152 post:
1153 security:
1154 - OAuth2:
1155 - admin
1156 tags:
1157 - Instance Follows
1158 summary: Follow a list of actors (PeerTube instance, channel or account)
1159 responses:
1160 '204':
1161 description: successful operation
1162 '500':
1163 description: cannot follow a non-HTTPS server
1164 requestBody:
1165 content:
1166 application/json:
1167 schema:
1168 type: object
1169 properties:
1170 hosts:
1171 type: array
1172 items:
1173 type: string
1174 format: hostname
1175 uniqueItems: true
1176 handles:
1177 type: array
1178 items:
1179 type: string
1180 uniqueItems: true
1181
1182 '/api/v1/server/following/{hostOrHandle}':
1183 delete:
1184 summary: Unfollow an actor (PeerTube instance, channel or account)
1185 security:
1186 - OAuth2:
1187 - admin
1188 tags:
1189 - Instance Follows
1190 parameters:
1191 - name: hostOrHandle
1192 in: path
1193 required: true
1194 description: The hostOrHandle to unfollow
1195 schema:
1196 type: string
1197 responses:
1198 '204':
1199 description: successful operation
1200 '404':
1201 description: host or handle not found
1202
1203 /api/v1/users:
1204 post:
1205 summary: Create a user
1206 operationId: addUser
1207 security:
1208 - OAuth2:
1209 - admin
1210 tags:
1211 - Users
1212 responses:
1213 '200':
1214 description: user created
1215 content:
1216 application/json:
1217 schema:
1218 $ref: '#/components/schemas/AddUserResponse'
1219 links:
1220 # GET /users/{id}
1221 GetUser:
1222 operationId: getUser
1223 parameters:
1224 id: '$response.body#/user/id'
1225 # PUT /users/{id}
1226 PutUser:
1227 operationId: putUser
1228 parameters:
1229 id: '$response.body#/user/id'
1230 # DELETE /users/{id}
1231 DelUser:
1232 operationId: delUser
1233 parameters:
1234 id: '$response.body#/user/id'
1235 '403':
1236 description: insufficient authority to create an admin or moderator
1237 requestBody:
1238 content:
1239 application/json:
1240 schema:
1241 $ref: '#/components/schemas/AddUser'
1242 description: |
1243 If the smtp server is configured, you can leave the password empty and an email will be sent
1244 asking the user to set it first.
1245 required: true
1246 get:
1247 summary: List users
1248 operationId: getUsers
1249 security:
1250 - OAuth2:
1251 - admin
1252 tags:
1253 - Users
1254 parameters:
1255 - $ref: '#/components/parameters/usersSearch'
1256 - $ref: '#/components/parameters/usersBlocked'
1257 - $ref: '#/components/parameters/start'
1258 - $ref: '#/components/parameters/count'
1259 - $ref: '#/components/parameters/usersSort'
1260 responses:
1261 '200':
1262 description: successful operation
1263 content:
1264 application/json:
1265 schema:
1266 type: array
1267 items:
1268 $ref: '#/components/schemas/User'
1269
1270 '/api/v1/users/{id}':
1271 parameters:
1272 - $ref: '#/components/parameters/id'
1273 delete:
1274 summary: Delete a user
1275 security:
1276 - OAuth2:
1277 - admin
1278 tags:
1279 - Users
1280 operationId: delUser
1281 responses:
1282 '204':
1283 description: successful operation
1284 get:
1285 summary: Get a user
1286 security:
1287 - OAuth2: []
1288 tags:
1289 - Users
1290 operationId: getUser
1291 parameters:
1292 - name: withStats
1293 in: query
1294 description: include statistics about the user (only available as a moderator/admin)
1295 schema:
1296 type: boolean
1297 responses:
1298 '200':
1299 x-summary: successful operation
1300 description: |
1301 As an admin/moderator, you can request a response augmented with statistics about the user's
1302 moderation relations and videos usage, by using the `withStats` parameter.
1303 content:
1304 application/json:
1305 schema:
1306 oneOf:
1307 - $ref: '#/components/schemas/User'
1308 - $ref: '#/components/schemas/UserWithStats'
1309 put:
1310 summary: Update a user
1311 security:
1312 - OAuth2: []
1313 tags:
1314 - Users
1315 operationId: putUser
1316 responses:
1317 '204':
1318 description: successful operation
1319 requestBody:
1320 content:
1321 application/json:
1322 schema:
1323 $ref: '#/components/schemas/UpdateUser'
1324 required: true
1325
1326 /api/v1/oauth-clients/local:
1327 get:
1328 summary: Login prerequisite
1329 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
1330 operationId: getOAuthClient
1331 tags:
1332 - Session
1333 responses:
1334 '200':
1335 description: successful operation
1336 content:
1337 application/json:
1338 schema:
1339 $ref: '#/components/schemas/OAuthClient'
1340 links:
1341 UseOAuthClientToLogin:
1342 operationId: getOAuthToken
1343 parameters:
1344 client_id: '$response.body#/client_id'
1345 client_secret: '$response.body#/client_secret'
1346 x-codeSamples:
1347 - lang: Shell
1348 source: |
1349 API="https://peertube2.cpy.re/api/v1"
1350
1351 ## AUTH
1352 curl -s "$API/oauth-clients/local"
1353
1354 /api/v1/users/token:
1355 post:
1356 summary: Login
1357 operationId: getOAuthToken
1358 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
1359 tags:
1360 - Session
1361 requestBody:
1362 content:
1363 application/x-www-form-urlencoded:
1364 schema:
1365 oneOf:
1366 - $ref: '#/components/schemas/OAuthToken-password'
1367 - $ref: '#/components/schemas/OAuthToken-refresh_token'
1368 discriminator:
1369 propertyName: grant_type
1370 mapping:
1371 password: '#/components/schemas/OAuthToken-password'
1372 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
1373 responses:
1374 '200':
1375 description: successful operation
1376 content:
1377 application/json:
1378 schema:
1379 type: object
1380 properties:
1381 token_type:
1382 type: string
1383 example: Bearer
1384 access_token:
1385 type: string
1386 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
1387 description: valid for 1 day
1388 refresh_token:
1389 type: string
1390 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
1391 description: valid for 2 weeks
1392 expires_in:
1393 type: integer
1394 minimum: 0
1395 example: 14399
1396 refresh_token_expires_in:
1397 type: integer
1398 minimum: 0
1399 example: 1209600
1400 '400':
1401 x-summary: client or credentials are invalid
1402 description: |
1403 Disambiguate via `type`:
1404 - `invalid_client` for an unmatched `client_id`
1405 - `invalid_grant` for unmatched credentials
1406 '401':
1407 x-summary: token expired
1408 description: |
1409 Disambiguate via `type`:
1410 - default value for a regular authentication failure
1411 - `invalid_token` for an expired token
1412 x-codeSamples:
1413 - lang: Shell
1414 source: |
1415 ## DEPENDENCIES: jq
1416 API="https://peertube2.cpy.re/api/v1"
1417 USERNAME="<your_username>"
1418 PASSWORD="<your_password>"
1419
1420 ## AUTH
1421 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1422 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1423 curl -s "$API/users/token" \
1424 --data client_id="$client_id" \
1425 --data client_secret="$client_secret" \
1426 --data grant_type=password \
1427 --data username="$USERNAME" \
1428 --data password="$PASSWORD" \
1429 | jq -r ".access_token"
1430
1431 /api/v1/users/revoke-token:
1432 post:
1433 summary: Logout
1434 description: Revokes your access token and its associated refresh token, destroying your current session.
1435 operationId: revokeOAuthToken
1436 tags:
1437 - Session
1438 security:
1439 - OAuth2: []
1440 responses:
1441 '200':
1442 description: successful operation
1443
1444 /api/v1/users/ask-send-verify-email:
1445 post:
1446 summary: Resend user verification link
1447 operationId: resendEmailToVerifyUser
1448 tags:
1449 - Users
1450 - Register
1451 requestBody:
1452 content:
1453 application/json:
1454 schema:
1455 type: object
1456 properties:
1457 email:
1458 type: string
1459 description: User email
1460 required:
1461 - email
1462 responses:
1463 '204':
1464 description: successful operation
1465
1466 /api/v1/users/registrations/ask-send-verify-email:
1467 post:
1468 summary: Resend verification link to registration email
1469 operationId: resendEmailToVerifyRegistration
1470 tags:
1471 - Register
1472 requestBody:
1473 content:
1474 application/json:
1475 schema:
1476 type: object
1477 properties:
1478 email:
1479 type: string
1480 description: Registration email
1481 required:
1482 - email
1483 responses:
1484 '204':
1485 description: successful operation
1486
1487 /api/v1/users/{id}/verify-email:
1488 post:
1489 summary: Verify a user
1490 operationId: verifyUser
1491 description: |
1492 Following a user registration, the new user will receive an email asking to click a link
1493 containing a secret.
1494 This endpoint can also be used to verify a new email set in the user account.
1495 tags:
1496 - Users
1497 - Register
1498 parameters:
1499 - $ref: '#/components/parameters/id'
1500 requestBody:
1501 content:
1502 application/json:
1503 schema:
1504 type: object
1505 properties:
1506 verificationString:
1507 type: string
1508 format: url
1509 isPendingEmail:
1510 type: boolean
1511 required:
1512 - verificationString
1513 responses:
1514 '204':
1515 description: successful operation
1516 '403':
1517 description: invalid verification string
1518 '404':
1519 description: user not found
1520
1521 /api/v1/users/registrations/{registrationId}/verify-email:
1522 post:
1523 summary: Verify a registration email
1524 operationId: verifyRegistrationEmail
1525 description: |
1526 Following a user registration request, the user will receive an email asking to click a link
1527 containing a secret.
1528 tags:
1529 - Register
1530 parameters:
1531 - $ref: '#/components/parameters/registrationId'
1532 requestBody:
1533 content:
1534 application/json:
1535 schema:
1536 type: object
1537 properties:
1538 verificationString:
1539 type: string
1540 format: url
1541 required:
1542 - verificationString
1543 responses:
1544 '204':
1545 description: successful operation
1546 '403':
1547 description: invalid verification string
1548 '404':
1549 description: registration not found
1550
1551 /api/v1/users/{id}/two-factor/request:
1552 post:
1553 summary: Request two factor auth
1554 operationId: requestTwoFactor
1555 description: Request two factor authentication for a user
1556 tags:
1557 - Users
1558 parameters:
1559 - $ref: '#/components/parameters/id'
1560 requestBody:
1561 content:
1562 application/json:
1563 schema:
1564 type: object
1565 properties:
1566 currentPassword:
1567 type: string
1568 description: Password of the currently authenticated user
1569 responses:
1570 '200':
1571 description: successful operation
1572 content:
1573 application/json:
1574 schema:
1575 type: array
1576 items:
1577 $ref: '#/components/schemas/RequestTwoFactorResponse'
1578 '403':
1579 description: invalid password
1580 '404':
1581 description: user not found
1582
1583 /api/v1/users/{id}/two-factor/confirm-request:
1584 post:
1585 summary: Confirm two factor auth
1586 operationId: confirmTwoFactorRequest
1587 description: Confirm a two factor authentication request
1588 tags:
1589 - Users
1590 parameters:
1591 - $ref: '#/components/parameters/id'
1592 requestBody:
1593 content:
1594 application/json:
1595 schema:
1596 type: object
1597 properties:
1598 requestToken:
1599 type: string
1600 description: Token to identify the two factor request
1601 otpToken:
1602 type: string
1603 description: OTP token generated by the app
1604 required:
1605 - requestToken
1606 - otpToken
1607 responses:
1608 '204':
1609 description: successful operation
1610 '403':
1611 description: invalid request token or OTP token
1612 '404':
1613 description: user not found
1614
1615 /api/v1/users/{id}/two-factor/disable:
1616 post:
1617 summary: Disable two factor auth
1618 operationId: disableTwoFactor
1619 description: Disable two factor authentication of a user
1620 tags:
1621 - Users
1622 parameters:
1623 - $ref: '#/components/parameters/id'
1624 requestBody:
1625 content:
1626 application/json:
1627 schema:
1628 type: object
1629 properties:
1630 currentPassword:
1631 type: string
1632 description: Password of the currently authenticated user
1633 responses:
1634 '204':
1635 description: successful operation
1636 '403':
1637 description: invalid password
1638 '404':
1639 description: user not found
1640
1641 /api/v1/users/me:
1642 get:
1643 summary: Get my user information
1644 operationId: getUserInfo
1645 security:
1646 - OAuth2:
1647 - user
1648 tags:
1649 - My User
1650 responses:
1651 '200':
1652 description: successful operation
1653 content:
1654 application/json:
1655 schema:
1656 type: array
1657 items:
1658 $ref: '#/components/schemas/User'
1659 put:
1660 summary: Update my user information
1661 operationId: putUserInfo
1662 security:
1663 - OAuth2:
1664 - user
1665 tags:
1666 - My User
1667 responses:
1668 '204':
1669 description: successful operation
1670 requestBody:
1671 content:
1672 application/json:
1673 schema:
1674 $ref: '#/components/schemas/UpdateMe'
1675 required: true
1676
1677 /api/v1/users/me/videos/imports:
1678 get:
1679 summary: Get video imports of my user
1680 security:
1681 - OAuth2:
1682 - user
1683 tags:
1684 - Videos
1685 - My User
1686 parameters:
1687 - $ref: '#/components/parameters/start'
1688 - $ref: '#/components/parameters/count'
1689 - $ref: '#/components/parameters/sort'
1690 -
1691 name: targetUrl
1692 in: query
1693 required: false
1694 description: Filter on import target URL
1695 schema:
1696 type: string
1697 -
1698 name: videoChannelSyncId
1699 in: query
1700 required: false
1701 description: Filter on imports created by a specific channel synchronization
1702 schema:
1703 type: number
1704 -
1705 name: search
1706 in: query
1707 required: false
1708 description: Search in video names
1709 schema:
1710 type: string
1711 responses:
1712 '200':
1713 description: successful operation
1714 content:
1715 application/json:
1716 schema:
1717 $ref: '#/components/schemas/VideoImportsList'
1718
1719 /api/v1/users/me/video-quota-used:
1720 get:
1721 summary: Get my user used quota
1722 security:
1723 - OAuth2:
1724 - user
1725 tags:
1726 - My User
1727 responses:
1728 '200':
1729 description: successful operation
1730 content:
1731 application/json:
1732 schema:
1733 type: object
1734 properties:
1735 videoQuotaUsed:
1736 type: number
1737 description: The user video quota used so far in bytes
1738 example: 16810141515
1739 videoQuotaUsedDaily:
1740 type: number
1741 description: The user video quota used today in bytes
1742 example: 1681014151
1743
1744 '/api/v1/users/me/videos/{videoId}/rating':
1745 get:
1746 summary: Get rate of my user for a video
1747 security:
1748 - OAuth2: []
1749 tags:
1750 - My User
1751 - Video Rates
1752 parameters:
1753 - name: videoId
1754 in: path
1755 required: true
1756 description: The video id
1757 schema:
1758 $ref: '#/components/schemas/Video/properties/id'
1759 responses:
1760 '200':
1761 description: successful operation
1762 content:
1763 application/json:
1764 schema:
1765 $ref: '#/components/schemas/GetMeVideoRating'
1766
1767 /api/v1/users/me/videos:
1768 get:
1769 summary: Get videos of my user
1770 security:
1771 - OAuth2:
1772 - user
1773 tags:
1774 - My User
1775 - Videos
1776 parameters:
1777 - $ref: '#/components/parameters/start'
1778 - $ref: '#/components/parameters/count'
1779 - $ref: '#/components/parameters/sort'
1780 responses:
1781 '200':
1782 description: successful operation
1783 content:
1784 application/json:
1785 schema:
1786 $ref: '#/components/schemas/VideoListResponse'
1787
1788 /api/v1/users/me/subscriptions:
1789 get:
1790 summary: Get my user subscriptions
1791 security:
1792 - OAuth2:
1793 - user
1794 tags:
1795 - My Subscriptions
1796 parameters:
1797 - $ref: '#/components/parameters/start'
1798 - $ref: '#/components/parameters/count'
1799 - $ref: '#/components/parameters/sort'
1800 responses:
1801 '200':
1802 description: successful operation
1803 content:
1804 application/json:
1805 schema:
1806 $ref: '#/components/schemas/VideoChannelList'
1807 post:
1808 tags:
1809 - My Subscriptions
1810 summary: Add subscription to my user
1811 security:
1812 - OAuth2:
1813 - user
1814 requestBody:
1815 content:
1816 application/json:
1817 schema:
1818 type: object
1819 properties:
1820 uri:
1821 type: string
1822 format: uri
1823 description: uri of the video channels to subscribe to
1824 required:
1825 - uri
1826 examples:
1827 default:
1828 value:
1829 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1830 responses:
1831 '200':
1832 description: successful operation
1833
1834 /api/v1/users/me/subscriptions/exist:
1835 get:
1836 summary: Get if subscriptions exist for my user
1837 security:
1838 - OAuth2:
1839 - user
1840 tags:
1841 - My Subscriptions
1842 parameters:
1843 - $ref: '#/components/parameters/subscriptionsUris'
1844 responses:
1845 '200':
1846 description: successful operation
1847 content:
1848 application/json:
1849 schema:
1850 type: object
1851
1852 /api/v1/users/me/subscriptions/videos:
1853 get:
1854 summary: List videos of subscriptions of my user
1855 security:
1856 - OAuth2:
1857 - user
1858 tags:
1859 - My Subscriptions
1860 - Videos
1861 parameters:
1862 - $ref: '#/components/parameters/categoryOneOf'
1863 - $ref: '#/components/parameters/isLive'
1864 - $ref: '#/components/parameters/tagsOneOf'
1865 - $ref: '#/components/parameters/tagsAllOf'
1866 - $ref: '#/components/parameters/licenceOneOf'
1867 - $ref: '#/components/parameters/languageOneOf'
1868 - $ref: '#/components/parameters/nsfw'
1869 - $ref: '#/components/parameters/isLocal'
1870 - $ref: '#/components/parameters/include'
1871 - $ref: '#/components/parameters/privacyOneOf'
1872 - $ref: '#/components/parameters/hasHLSFiles'
1873 - $ref: '#/components/parameters/hasWebtorrentFiles'
1874 - $ref: '#/components/parameters/skipCount'
1875 - $ref: '#/components/parameters/start'
1876 - $ref: '#/components/parameters/count'
1877 - $ref: '#/components/parameters/videosSort'
1878 - $ref: '#/components/parameters/excludeAlreadyWatched'
1879 responses:
1880 '200':
1881 description: successful operation
1882 content:
1883 application/json:
1884 schema:
1885 $ref: '#/components/schemas/VideoListResponse'
1886
1887 '/api/v1/users/me/subscriptions/{subscriptionHandle}':
1888 get:
1889 summary: Get subscription of my user
1890 security:
1891 - OAuth2:
1892 - user
1893 tags:
1894 - My Subscriptions
1895 parameters:
1896 - $ref: '#/components/parameters/subscriptionHandle'
1897 responses:
1898 '200':
1899 description: successful operation
1900 content:
1901 application/json:
1902 schema:
1903 $ref: '#/components/schemas/VideoChannel'
1904 delete:
1905 summary: Delete subscription of my user
1906 security:
1907 - OAuth2:
1908 - user
1909 tags:
1910 - My Subscriptions
1911 parameters:
1912 - $ref: '#/components/parameters/subscriptionHandle'
1913 responses:
1914 '200':
1915 description: successful operation
1916
1917 /api/v1/users/me/notifications:
1918 get:
1919 summary: List my notifications
1920 security:
1921 - OAuth2: []
1922 tags:
1923 - My Notifications
1924 parameters:
1925 - name: unread
1926 in: query
1927 description: only list unread notifications
1928 schema:
1929 type: boolean
1930 - $ref: '#/components/parameters/start'
1931 - $ref: '#/components/parameters/count'
1932 - $ref: '#/components/parameters/sort'
1933 responses:
1934 '200':
1935 description: successful operation
1936 content:
1937 application/json:
1938 schema:
1939 $ref: '#/components/schemas/NotificationListResponse'
1940
1941 /api/v1/users/me/notifications/read:
1942 post:
1943 summary: Mark notifications as read by their id
1944 security:
1945 - OAuth2: []
1946 tags:
1947 - My Notifications
1948 requestBody:
1949 content:
1950 application/json:
1951 schema:
1952 type: object
1953 properties:
1954 ids:
1955 type: array
1956 description: ids of the notifications to mark as read
1957 items:
1958 type: integer
1959 required:
1960 - ids
1961 responses:
1962 '204':
1963 description: successful operation
1964
1965 /api/v1/users/me/notifications/read-all:
1966 post:
1967 summary: Mark all my notification as read
1968 security:
1969 - OAuth2: []
1970 tags:
1971 - My Notifications
1972 responses:
1973 '204':
1974 description: successful operation
1975
1976 /api/v1/users/me/notification-settings:
1977 put:
1978 summary: Update my notification settings
1979 security:
1980 - OAuth2: []
1981 tags:
1982 - My Notifications
1983 requestBody:
1984 content:
1985 application/json:
1986 schema:
1987 type: object
1988 properties:
1989 newVideoFromSubscription:
1990 $ref: '#/components/schemas/NotificationSettingValue'
1991 newCommentOnMyVideo:
1992 $ref: '#/components/schemas/NotificationSettingValue'
1993 abuseAsModerator:
1994 $ref: '#/components/schemas/NotificationSettingValue'
1995 videoAutoBlacklistAsModerator:
1996 $ref: '#/components/schemas/NotificationSettingValue'
1997 blacklistOnMyVideo:
1998 $ref: '#/components/schemas/NotificationSettingValue'
1999 myVideoPublished:
2000 $ref: '#/components/schemas/NotificationSettingValue'
2001 myVideoImportFinished:
2002 $ref: '#/components/schemas/NotificationSettingValue'
2003 newFollow:
2004 $ref: '#/components/schemas/NotificationSettingValue'
2005 newUserRegistration:
2006 $ref: '#/components/schemas/NotificationSettingValue'
2007 commentMention:
2008 $ref: '#/components/schemas/NotificationSettingValue'
2009 newInstanceFollower:
2010 $ref: '#/components/schemas/NotificationSettingValue'
2011 autoInstanceFollowing:
2012 $ref: '#/components/schemas/NotificationSettingValue'
2013 responses:
2014 '204':
2015 description: successful operation
2016
2017 /api/v1/users/me/history/videos:
2018 get:
2019 summary: List watched videos history
2020 security:
2021 - OAuth2: []
2022 tags:
2023 - My History
2024 parameters:
2025 - $ref: '#/components/parameters/start'
2026 - $ref: '#/components/parameters/count'
2027 - $ref: '#/components/parameters/search'
2028 responses:
2029 '200':
2030 description: successful operation
2031 content:
2032 application/json:
2033 schema:
2034 $ref: '#/components/schemas/VideoListResponse'
2035
2036 /api/v1/users/me/history/videos/{videoId}:
2037 delete:
2038 summary: Delete history element
2039 security:
2040 - OAuth2: []
2041 tags:
2042 - My History
2043 parameters:
2044 - name: videoId
2045 in: path
2046 required: true
2047 schema:
2048 $ref: '#/components/schemas/Video/properties/id'
2049 responses:
2050 '204':
2051 description: successful operation
2052
2053 /api/v1/users/me/history/videos/remove:
2054 post:
2055 summary: Clear video history
2056 security:
2057 - OAuth2: []
2058 tags:
2059 - My History
2060 requestBody:
2061 content:
2062 multipart/form-data:
2063 schema:
2064 type: object
2065 properties:
2066 beforeDate:
2067 description: history before this date will be deleted
2068 type: string
2069 format: date-time
2070 responses:
2071 '204':
2072 description: successful operation
2073
2074 /api/v1/users/me/avatar/pick:
2075 post:
2076 summary: Update my user avatar
2077 security:
2078 - OAuth2: []
2079 tags:
2080 - My User
2081 responses:
2082 '200':
2083 description: successful operation
2084 content:
2085 application/json:
2086 schema:
2087 type: object
2088 properties:
2089 avatars:
2090 type: array
2091 items:
2092 $ref: '#/components/schemas/ActorImage'
2093 '413':
2094 description: image file too large
2095 headers:
2096 X-File-Maximum-Size:
2097 schema:
2098 type: string
2099 format: Nginx size
2100 description: Maximum file size for the avatar
2101 requestBody:
2102 content:
2103 multipart/form-data:
2104 schema:
2105 type: object
2106 properties:
2107 avatarfile:
2108 description: The file to upload
2109 type: string
2110 format: binary
2111 encoding:
2112 avatarfile:
2113 contentType: image/png, image/jpeg
2114
2115 /api/v1/users/me/avatar:
2116 delete:
2117 summary: Delete my avatar
2118 security:
2119 - OAuth2: []
2120 tags:
2121 - My User
2122 responses:
2123 '204':
2124 description: successful operation
2125
2126 /api/v1/users/register:
2127 post:
2128 summary: Register a user
2129 operationId: registerUser
2130 description: Signup has to be enabled and signup approval is not required
2131 tags:
2132 - Register
2133 responses:
2134 '204':
2135 description: successful operation
2136 '400':
2137 description: request error
2138 '403':
2139 description: user registration is not enabled, user limit is reached, registration is not allowed for the ip, requires approval or blocked by a plugin
2140 '409':
2141 description: 'a user with this username, channel name or email already exists'
2142 requestBody:
2143 content:
2144 application/json:
2145 schema:
2146 $ref: '#/components/schemas/RegisterUser'
2147 required: true
2148
2149 /api/v1/users/registrations/request:
2150 post:
2151 summary: Request registration
2152 description: Signup has to be enabled and require approval on the instance
2153 operationId: requestRegistration
2154 tags:
2155 - Register
2156 responses:
2157 '200':
2158 description: successful operation
2159 content:
2160 application/json:
2161 schema:
2162 $ref: '#/components/schemas/UserRegistration'
2163 '400':
2164 description: request error or signup approval is not enabled on the instance
2165 '403':
2166 description: user registration is not enabled, user limit is reached, registration is not allowed for the ip or blocked by a plugin
2167 '409':
2168 description: 'a user or registration with this username, channel name or email already exists'
2169 requestBody:
2170 content:
2171 application/json:
2172 schema:
2173 $ref: '#/components/schemas/UserRegistrationRequest'
2174
2175 /api/v1/users/registrations/{registrationId}/accept:
2176 post:
2177 security:
2178 - OAuth2:
2179 - admin
2180 - moderator
2181 summary: Accept registration
2182 operationId: acceptRegistration
2183 tags:
2184 - Register
2185 parameters:
2186 - $ref: '#/components/parameters/registrationId'
2187 requestBody:
2188 content:
2189 application/json:
2190 schema:
2191 $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
2192 responses:
2193 '204':
2194 description: successful operation
2195
2196 /api/v1/users/registrations/{registrationId}/reject:
2197 post:
2198 security:
2199 - OAuth2:
2200 - admin
2201 - moderator
2202 summary: Reject registration
2203 operationId: rejectRegistration
2204 tags:
2205 - Register
2206 parameters:
2207 - $ref: '#/components/parameters/registrationId'
2208 requestBody:
2209 content:
2210 application/json:
2211 schema:
2212 $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
2213 responses:
2214 '204':
2215 description: successful operation
2216
2217 /api/v1/users/registrations/{registrationId}:
2218 delete:
2219 security:
2220 - OAuth2:
2221 - admin
2222 - moderator
2223 summary: Delete registration
2224 description: 'Delete the registration entry. It will not remove the user associated with this registration (if any)'
2225 operationId: deleteRegistration
2226 tags:
2227 - Register
2228 parameters:
2229 - $ref: '#/components/parameters/registrationId'
2230 responses:
2231 '204':
2232 description: successful operation
2233
2234 /api/v1/users/registrations:
2235 get:
2236 security:
2237 - OAuth2:
2238 - admin
2239 - moderator
2240 summary: List registrations
2241 operationId: listRegistrations
2242 tags:
2243 - Register
2244 parameters:
2245 - $ref: '#/components/parameters/start'
2246 - $ref: '#/components/parameters/count'
2247 - name: search
2248 in: query
2249 required: false
2250 schema:
2251 type: string
2252 - name: sort
2253 in: query
2254 required: false
2255 schema:
2256 type: string
2257 enum:
2258 - -createdAt
2259 - createdAt
2260 - state
2261 - -state
2262 responses:
2263 '200':
2264 description: successful operation
2265 content:
2266 application/json:
2267 schema:
2268 type: object
2269 properties:
2270 total:
2271 type: integer
2272 example: 1
2273 data:
2274 type: array
2275 items:
2276 $ref: '#/components/schemas/UserRegistration'
2277
2278 /api/v1/videos/ownership:
2279 get:
2280 summary: List video ownership changes
2281 tags:
2282 - Video Ownership Change
2283 security:
2284 - OAuth2: []
2285 responses:
2286 '200':
2287 description: successful operation
2288
2289 '/api/v1/videos/ownership/{id}/accept':
2290 post:
2291 summary: Accept ownership change request
2292 tags:
2293 - Video Ownership Change
2294 security:
2295 - OAuth2: []
2296 parameters:
2297 - $ref: '#/components/parameters/idOrUUID'
2298 responses:
2299 '204':
2300 description: successful operation
2301 '403':
2302 description: cannot terminate an ownership change of another user
2303 '404':
2304 description: video ownership change not found
2305
2306 '/api/v1/videos/ownership/{id}/refuse':
2307 post:
2308 summary: Refuse ownership change request
2309 tags:
2310 - Video Ownership Change
2311 security:
2312 - OAuth2: []
2313 parameters:
2314 - $ref: '#/components/parameters/idOrUUID'
2315 responses:
2316 '204':
2317 description: successful operation
2318 '403':
2319 description: cannot terminate an ownership change of another user
2320 '404':
2321 description: video ownership change not found
2322
2323 '/api/v1/videos/{id}/give-ownership':
2324 post:
2325 summary: Request ownership change
2326 tags:
2327 - Video Ownership Change
2328 security:
2329 - OAuth2: []
2330 parameters:
2331 - $ref: '#/components/parameters/idOrUUID'
2332 requestBody:
2333 required: true
2334 content:
2335 application/x-www-form-urlencoded:
2336 schema:
2337 type: object
2338 properties:
2339 username:
2340 type: string
2341 required:
2342 - username
2343 responses:
2344 '204':
2345 description: successful operation
2346 '400':
2347 description: changing video ownership to a remote account is not supported yet
2348 '404':
2349 description: video not found
2350
2351 '/api/v1/videos/{id}/token':
2352 post:
2353 summary: Request video token
2354 operationId: requestVideoToken
2355 description: Request special tokens that expire quickly to use them in some context (like accessing private static files)
2356 tags:
2357 - Video
2358 security:
2359 - OAuth2: []
2360 parameters:
2361 - $ref: '#/components/parameters/idOrUUID'
2362 responses:
2363 '200':
2364 description: successful operation
2365 content:
2366 application/json:
2367 schema:
2368 $ref: '#/components/schemas/VideoTokenResponse'
2369 '400':
2370 description: incorrect parameters
2371 '404':
2372 description: video not found
2373
2374 /api/v1/videos/{id}/studio/edit:
2375 post:
2376 summary: Create a studio task
2377 tags:
2378 - Video Transcoding
2379 - Video
2380 description: Create a task to edit a video (cut, add intro/outro etc)
2381 security:
2382 - OAuth2: []
2383 parameters:
2384 - $ref: '#/components/parameters/idOrUUID'
2385 requestBody:
2386 required: true
2387 content:
2388 application/x-www-form-urlencoded:
2389 schema:
2390 $ref: '#/components/schemas/VideoStudioCreateTask'
2391 responses:
2392 '204':
2393 description: successful operation
2394 '400':
2395 description: incorrect parameters
2396 '404':
2397 description: video not found
2398
2399 /api/v1/videos:
2400 get:
2401 summary: List videos
2402 operationId: getVideos
2403 tags:
2404 - Video
2405 parameters:
2406 - $ref: '#/components/parameters/categoryOneOf'
2407 - $ref: '#/components/parameters/isLive'
2408 - $ref: '#/components/parameters/tagsOneOf'
2409 - $ref: '#/components/parameters/tagsAllOf'
2410 - $ref: '#/components/parameters/licenceOneOf'
2411 - $ref: '#/components/parameters/languageOneOf'
2412 - $ref: '#/components/parameters/nsfw'
2413 - $ref: '#/components/parameters/isLocal'
2414 - $ref: '#/components/parameters/include'
2415 - $ref: '#/components/parameters/privacyOneOf'
2416 - $ref: '#/components/parameters/hasHLSFiles'
2417 - $ref: '#/components/parameters/hasWebtorrentFiles'
2418 - $ref: '#/components/parameters/skipCount'
2419 - $ref: '#/components/parameters/start'
2420 - $ref: '#/components/parameters/count'
2421 - $ref: '#/components/parameters/videosSort'
2422 - $ref: '#/components/parameters/excludeAlreadyWatched'
2423 responses:
2424 '200':
2425 description: successful operation
2426 content:
2427 application/json:
2428 schema:
2429 $ref: '#/components/schemas/VideoListResponse'
2430
2431 /api/v1/videos/categories:
2432 get:
2433 summary: List available video categories
2434 operationId: getCategories
2435 tags:
2436 - Video
2437 responses:
2438 '200':
2439 description: successful operation
2440 content:
2441 application/json:
2442 schema:
2443 type: array
2444 items:
2445 type: string
2446 examples:
2447 nightly:
2448 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
2449
2450 /api/v1/videos/licences:
2451 get:
2452 summary: List available video licences
2453 operationId: getLicences
2454 tags:
2455 - Video
2456 responses:
2457 '200':
2458 description: successful operation
2459 content:
2460 application/json:
2461 schema:
2462 type: array
2463 items:
2464 type: string
2465 examples:
2466 nightly:
2467 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
2468
2469 /api/v1/videos/languages:
2470 get:
2471 summary: List available video languages
2472 operationId: getLanguages
2473 tags:
2474 - Video
2475 responses:
2476 '200':
2477 description: successful operation
2478 content:
2479 application/json:
2480 schema:
2481 type: array
2482 items:
2483 type: string
2484 examples:
2485 nightly:
2486 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
2487
2488 /api/v1/videos/privacies:
2489 get:
2490 summary: List available video privacy policies
2491 operationId: getVideoPrivacyPolicies
2492 tags:
2493 - Video
2494 responses:
2495 '200':
2496 description: successful operation
2497 content:
2498 application/json:
2499 schema:
2500 type: array
2501 items:
2502 type: string
2503 examples:
2504 nightly:
2505 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
2506
2507 '/api/v1/videos/{id}':
2508 put:
2509 summary: Update a video
2510 operationId: putVideo
2511 security:
2512 - OAuth2: []
2513 tags:
2514 - Video
2515 parameters:
2516 - $ref: '#/components/parameters/idOrUUID'
2517 responses:
2518 '204':
2519 description: successful operation
2520 requestBody:
2521 content:
2522 multipart/form-data:
2523 schema:
2524 type: object
2525 properties:
2526 thumbnailfile:
2527 description: Video thumbnail file
2528 type: string
2529 format: binary
2530 previewfile:
2531 description: Video preview file
2532 type: string
2533 format: binary
2534 category:
2535 $ref: '#/components/schemas/VideoCategorySet'
2536 licence:
2537 $ref: '#/components/schemas/VideoLicenceSet'
2538 language:
2539 $ref: '#/components/schemas/VideoLanguageSet'
2540 privacy:
2541 $ref: '#/components/schemas/VideoPrivacySet'
2542 description:
2543 description: Video description
2544 type: string
2545 waitTranscoding:
2546 description: Whether or not we wait transcoding before publish the video
2547 type: string
2548 support:
2549 description: A text tell the audience how to support the video creator
2550 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2551 type: string
2552 nsfw:
2553 description: Whether or not this video contains sensitive content
2554 type: boolean
2555 name:
2556 description: Video name
2557 type: string
2558 minLength: 3
2559 maxLength: 120
2560 tags:
2561 description: Video tags (maximum 5 tags each between 2 and 30 characters)
2562 type: array
2563 minItems: 1
2564 maxItems: 5
2565 items:
2566 type: string
2567 minLength: 2
2568 maxLength: 30
2569 commentsEnabled:
2570 description: Enable or disable comments for this video
2571 type: boolean
2572 downloadEnabled:
2573 description: Enable or disable downloading for this video
2574 type: boolean
2575 originallyPublishedAt:
2576 description: Date when the content was originally published
2577 type: string
2578 format: date-time
2579 scheduleUpdate:
2580 $ref: '#/components/schemas/VideoScheduledUpdate'
2581 encoding:
2582 thumbnailfile:
2583 contentType: image/jpeg
2584 previewfile:
2585 contentType: image/jpeg
2586 get:
2587 summary: Get a video
2588 operationId: getVideo
2589 tags:
2590 - Video
2591 parameters:
2592 - $ref: '#/components/parameters/idOrUUID'
2593 responses:
2594 '200':
2595 description: successful operation
2596 content:
2597 application/json:
2598 schema:
2599 $ref: '#/components/schemas/VideoDetails'
2600 delete:
2601 summary: Delete a video
2602 operationId: delVideo
2603 security:
2604 - OAuth2: []
2605 tags:
2606 - Video
2607 parameters:
2608 - $ref: '#/components/parameters/idOrUUID'
2609 responses:
2610 '204':
2611 description: successful operation
2612
2613 '/api/v1/videos/{id}/description':
2614 get:
2615 summary: Get complete video description
2616 operationId: getVideoDesc
2617 tags:
2618 - Video
2619 parameters:
2620 - $ref: '#/components/parameters/idOrUUID'
2621 responses:
2622 '200':
2623 description: successful operation
2624 content:
2625 application/json:
2626 schema:
2627 nullable: true
2628 type: string
2629 minLength: 3
2630 maxLength: 10000
2631 example: |
2632 **[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)**
2633
2634 '/api/v1/videos/{id}/source':
2635 post:
2636 summary: Get video source file metadata
2637 operationId: getVideoSource
2638 tags:
2639 - Video
2640 parameters:
2641 - $ref: '#/components/parameters/idOrUUID'
2642 responses:
2643 '200':
2644 description: successful operation
2645 content:
2646 application/json:
2647 schema:
2648 $ref: '#/components/schemas/VideoSource'
2649
2650 '/api/v1/videos/{id}/views':
2651 post:
2652 summary: Notify user is watching a video
2653 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.
2654 operationId: addView
2655 tags:
2656 - Video
2657 parameters:
2658 - $ref: '#/components/parameters/idOrUUID'
2659 requestBody:
2660 content:
2661 application/json:
2662 schema:
2663 $ref: '#/components/schemas/UserViewingVideo'
2664 required: true
2665 responses:
2666 '204':
2667 description: successful operation
2668
2669 '/api/v1/videos/{id}/watching':
2670 put:
2671 summary: Set watching progress of a video
2672 deprecated: true
2673 description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
2674 tags:
2675 - Video
2676 security:
2677 - OAuth2: []
2678 parameters:
2679 - $ref: '#/components/parameters/idOrUUID'
2680 requestBody:
2681 content:
2682 application/json:
2683 schema:
2684 $ref: '#/components/schemas/UserViewingVideo'
2685 required: true
2686 responses:
2687 '204':
2688 description: successful operation
2689
2690 '/api/v1/videos/{id}/stats/overall':
2691 get:
2692 summary: Get overall stats of a video
2693 tags:
2694 - Video Stats
2695 security:
2696 - OAuth2: []
2697 parameters:
2698 - $ref: '#/components/parameters/idOrUUID'
2699 - name: startDate
2700 in: query
2701 description: Filter stats by start date
2702 schema:
2703 type: string
2704 format: date-time
2705 - name: endDate
2706 in: query
2707 description: Filter stats by end date
2708 schema:
2709 type: string
2710 format: date-time
2711 responses:
2712 '200':
2713 description: successful operation
2714 content:
2715 application/json:
2716 schema:
2717 $ref: '#/components/schemas/VideoStatsOverall'
2718
2719 '/api/v1/videos/{id}/stats/retention':
2720 get:
2721 summary: Get retention stats of a video
2722 tags:
2723 - Video Stats
2724 security:
2725 - OAuth2: []
2726 parameters:
2727 - $ref: '#/components/parameters/idOrUUID'
2728 responses:
2729 '200':
2730 description: successful operation
2731 content:
2732 application/json:
2733 schema:
2734 $ref: '#/components/schemas/VideoStatsRetention'
2735
2736 '/api/v1/videos/{id}/stats/timeseries/{metric}':
2737 get:
2738 summary: Get timeserie stats of a video
2739 tags:
2740 - Video Stats
2741 security:
2742 - OAuth2: []
2743 parameters:
2744 - $ref: '#/components/parameters/idOrUUID'
2745 -
2746 name: metric
2747 in: path
2748 required: true
2749 description: The metric to get
2750 schema:
2751 type: string
2752 enum:
2753 - 'viewers'
2754 - 'aggregateWatchTime'
2755 - name: startDate
2756 in: query
2757 description: Filter stats by start date
2758 schema:
2759 type: string
2760 format: date-time
2761 - name: endDate
2762 in: query
2763 description: Filter stats by end date
2764 schema:
2765 type: string
2766 format: date-time
2767 responses:
2768 '200':
2769 description: successful operation
2770 content:
2771 application/json:
2772 schema:
2773 $ref: '#/components/schemas/VideoStatsTimeserie'
2774
2775 /api/v1/videos/upload:
2776 post:
2777 summary: Upload a video
2778 description: Uses a single request to upload a video.
2779 operationId: uploadLegacy
2780 security:
2781 - OAuth2: []
2782 tags:
2783 - Video
2784 - Video Upload
2785 responses:
2786 '200':
2787 description: successful operation
2788 content:
2789 application/json:
2790 schema:
2791 $ref: '#/components/schemas/VideoUploadResponse'
2792 '403':
2793 description: video didn't pass upload filter
2794 '408':
2795 description: upload has timed out
2796 '413':
2797 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
2798 description: |
2799 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
2800 - `quota_reached` for quota limits whether daily or global
2801 headers:
2802 X-File-Maximum-Size:
2803 schema:
2804 type: string
2805 format: Nginx size
2806 description: Maximum file size for the video
2807 '415':
2808 description: video type unsupported
2809 '422':
2810 description: video unreadable
2811 requestBody:
2812 content:
2813 multipart/form-data:
2814 schema:
2815 $ref: '#/components/schemas/VideoUploadRequestLegacy'
2816 encoding:
2817 videofile:
2818 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
2819 thumbnailfile:
2820 contentType: image/jpeg
2821 previewfile:
2822 contentType: image/jpeg
2823 x-codeSamples:
2824 - lang: Shell
2825 source: |
2826 ## DEPENDENCIES: jq
2827 USERNAME="<your_username>"
2828 PASSWORD="<your_password>"
2829 FILE_PATH="<your_file_path>"
2830 CHANNEL_ID="<your_channel_id>"
2831 NAME="<video_name>"
2832 API="https://peertube2.cpy.re/api/v1"
2833
2834 ## AUTH
2835 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
2836 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
2837 token=$(curl -s "$API/users/token" \
2838 --data client_id="$client_id" \
2839 --data client_secret="$client_secret" \
2840 --data grant_type=password \
2841 --data username="$USERNAME" \
2842 --data password="$PASSWORD" \
2843 | jq -r ".access_token")
2844
2845 ## VIDEO UPLOAD
2846 curl -s "$API/videos/upload" \
2847 -H "Authorization: Bearer $token" \
2848 --max-time 600 \
2849 --form videofile=@"$FILE_PATH" \
2850 --form channelId=$CHANNEL_ID \
2851 --form name="$NAME"
2852
2853 /api/v1/videos/upload-resumable:
2854 post:
2855 summary: Initialize the resumable upload of a video
2856 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
2857 operationId: uploadResumableInit
2858 security:
2859 - OAuth2: []
2860 tags:
2861 - Video
2862 - Video Upload
2863 parameters:
2864 - name: X-Upload-Content-Length
2865 in: header
2866 schema:
2867 type: number
2868 example: 2469036
2869 required: true
2870 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2871 - name: X-Upload-Content-Type
2872 in: header
2873 schema:
2874 type: string
2875 format: mimetype
2876 example: video/mp4
2877 required: true
2878 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2879 requestBody:
2880 content:
2881 application/json:
2882 schema:
2883 $ref: '#/components/schemas/VideoUploadRequestResumable'
2884 responses:
2885 '200':
2886 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2887 '201':
2888 description: created
2889 headers:
2890 Location:
2891 schema:
2892 type: string
2893 format: url
2894 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2895 Content-Length:
2896 schema:
2897 type: number
2898 example: 0
2899 '413':
2900 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2901 description: |
2902 Disambiguate via `type`:
2903 - `max_file_size_reached` for the absolute file size limit
2904 - `quota_reached` for quota limits whether daily or global
2905 '415':
2906 description: video type unsupported
2907 put:
2908 summary: Send chunk for the resumable upload of a video
2909 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
2910 operationId: uploadResumable
2911 security:
2912 - OAuth2: []
2913 tags:
2914 - Video
2915 - Video Upload
2916 parameters:
2917 - name: upload_id
2918 in: query
2919 required: true
2920 description: |
2921 Created session id to proceed with. If you didn't send chunks in the last hour, it is
2922 not valid anymore and you need to initialize a new upload.
2923 schema:
2924 type: string
2925 - name: Content-Range
2926 in: header
2927 schema:
2928 type: string
2929 example: bytes 0-262143/2469036
2930 required: true
2931 description: |
2932 Specifies the bytes in the file that the request is uploading.
2933
2934 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2935 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2936 - name: Content-Length
2937 in: header
2938 schema:
2939 type: number
2940 example: 262144
2941 required: true
2942 description: |
2943 Size of the chunk that the request is sending.
2944
2945 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2946 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2947 requestBody:
2948 content:
2949 application/octet-stream:
2950 schema:
2951 type: string
2952 format: binary
2953 responses:
2954 '200':
2955 description: last chunk received
2956 headers:
2957 Content-Length:
2958 schema:
2959 type: number
2960 content:
2961 application/json:
2962 schema:
2963 $ref: '#/components/schemas/VideoUploadResponse'
2964 '308':
2965 description: resume incomplete
2966 headers:
2967 Range:
2968 schema:
2969 type: string
2970 example: bytes=0-262143
2971 Content-Length:
2972 schema:
2973 type: number
2974 example: 0
2975 '403':
2976 description: video didn't pass upload filter
2977 '404':
2978 description: upload not found
2979 '409':
2980 description: chunk doesn't match range
2981 '422':
2982 description: video unreadable
2983 '429':
2984 description: too many concurrent requests
2985 '503':
2986 description: upload is already being processed
2987 headers:
2988 'Retry-After':
2989 schema:
2990 type: number
2991 example: 300
2992 delete:
2993 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2994 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2995 operationId: uploadResumableCancel
2996 security:
2997 - OAuth2: []
2998 tags:
2999 - Video
3000 - Video Upload
3001 parameters:
3002 - name: upload_id
3003 in: query
3004 required: true
3005 description: |
3006 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
3007 not valid anymore and the upload session has already been deleted with its data ;-)
3008 schema:
3009 type: string
3010 - name: Content-Length
3011 in: header
3012 required: true
3013 schema:
3014 type: number
3015 example: 0
3016 responses:
3017 '204':
3018 description: upload cancelled
3019 headers:
3020 Content-Length:
3021 schema:
3022 type: number
3023 example: 0
3024 '404':
3025 description: upload not found
3026
3027 /api/v1/videos/imports:
3028 post:
3029 summary: Import a video
3030 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
3031 operationId: importVideo
3032 security:
3033 - OAuth2: []
3034 tags:
3035 - Video Imports
3036 - Video Upload
3037 requestBody:
3038 content:
3039 multipart/form-data:
3040 schema:
3041 $ref: '#/components/schemas/VideoCreateImport'
3042 encoding:
3043 torrentfile:
3044 contentType: application/x-bittorrent
3045 thumbnailfile:
3046 contentType: image/jpeg
3047 previewfile:
3048 contentType: image/jpeg
3049 responses:
3050 '200':
3051 description: successful operation
3052 content:
3053 application/json:
3054 schema:
3055 $ref: '#/components/schemas/VideoUploadResponse'
3056 '400':
3057 description: '`magnetUri` or `targetUrl` or a torrent file missing'
3058 '403':
3059 description: video didn't pass pre-import filter
3060 '409':
3061 description: HTTP or Torrent/magnetURI import not enabled
3062
3063 /api/v1/videos/imports/{id}/cancel:
3064 post:
3065 summary: Cancel video import
3066 description: Cancel a pending video import
3067 security:
3068 - OAuth2: []
3069 tags:
3070 - Video Imports
3071 parameters:
3072 - $ref: '#/components/parameters/id'
3073 responses:
3074 '204':
3075 description: successful operation
3076
3077 /api/v1/videos/imports/{id}:
3078 delete:
3079 summary: Delete video import
3080 description: Delete ended video import
3081 security:
3082 - OAuth2: []
3083 tags:
3084 - Video Imports
3085 parameters:
3086 - $ref: '#/components/parameters/id'
3087 responses:
3088 '204':
3089 description: successful operation
3090
3091 /api/v1/videos/live:
3092 post:
3093 summary: Create a live
3094 operationId: addLive
3095 security:
3096 - OAuth2: []
3097 tags:
3098 - Live Videos
3099 - Video
3100 responses:
3101 '200':
3102 description: successful operation
3103 content:
3104 application/json:
3105 schema:
3106 $ref: '#/components/schemas/VideoUploadResponse'
3107 '400':
3108 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
3109 description: |
3110 Disambiguate via `type`:
3111 - default type for a validation error
3112 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
3113 '403':
3114 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
3115 description: |
3116 Disambiguate via `type`:
3117 - `live_not_enabled` for a disabled live feature
3118 - `live_not_allowing_replay` for a disabled replay feature
3119 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
3120 - `max_user_lives_limit_reached` for the user concurrent live limit
3121 requestBody:
3122 content:
3123 multipart/form-data:
3124 schema:
3125 type: object
3126 properties:
3127 channelId:
3128 description: Channel id that will contain this live video
3129 type: integer
3130 saveReplay:
3131 type: boolean
3132 replaySettings:
3133 $ref: '#/components/schemas/LiveVideoReplaySettings'
3134 permanentLive:
3135 description: User can stream multiple times in a permanent live
3136 type: boolean
3137 latencyMode:
3138 description: User can select live latency mode if enabled by the instance
3139 $ref: '#/components/schemas/LiveVideoLatencyMode'
3140 thumbnailfile:
3141 description: Live video/replay thumbnail file
3142 type: string
3143 format: binary
3144 previewfile:
3145 description: Live video/replay preview file
3146 type: string
3147 format: binary
3148 privacy:
3149 $ref: '#/components/schemas/VideoPrivacySet'
3150 category:
3151 $ref: '#/components/schemas/VideoCategorySet'
3152 licence:
3153 $ref: '#/components/schemas/VideoLicenceSet'
3154 language:
3155 $ref: '#/components/schemas/VideoLanguageSet'
3156 description:
3157 description: Live video/replay description
3158 type: string
3159 support:
3160 description: A text tell the audience how to support the creator
3161 example: Please support our work on https://soutenir.framasoft.org/en/ <3
3162 type: string
3163 nsfw:
3164 description: Whether or not this live video/replay contains sensitive content
3165 type: boolean
3166 name:
3167 description: Live video/replay name
3168 type: string
3169 minLength: 3
3170 maxLength: 120
3171 tags:
3172 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
3173 type: array
3174 minItems: 1
3175 maxItems: 5
3176 items:
3177 type: string
3178 minLength: 2
3179 maxLength: 30
3180 commentsEnabled:
3181 description: Enable or disable comments for this live video/replay
3182 type: boolean
3183 downloadEnabled:
3184 description: Enable or disable downloading for the replay of this live video
3185 type: boolean
3186 required:
3187 - channelId
3188 - name
3189 encoding:
3190 thumbnailfile:
3191 contentType: image/jpeg
3192 previewfile:
3193 contentType: image/jpeg
3194
3195 /api/v1/videos/live/{id}:
3196 get:
3197 summary: Get information about a live
3198 operationId: getLiveId
3199 security:
3200 - OAuth2: []
3201 tags:
3202 - Live Videos
3203 - Video
3204 parameters:
3205 - $ref: '#/components/parameters/idOrUUID'
3206 responses:
3207 '200':
3208 description: successful operation
3209 content:
3210 application/json:
3211 schema:
3212 $ref: '#/components/schemas/LiveVideoResponse'
3213 put:
3214 summary: Update information about a live
3215 operationId: updateLiveId
3216 security:
3217 - OAuth2: []
3218 tags:
3219 - Live Videos
3220 - Video
3221 parameters:
3222 - $ref: '#/components/parameters/idOrUUID'
3223 requestBody:
3224 content:
3225 application/json:
3226 schema:
3227 $ref: '#/components/schemas/LiveVideoUpdate'
3228 responses:
3229 '204':
3230 description: successful operation
3231 '400':
3232 description: bad parameters or trying to update a live that has already started
3233 '403':
3234 description: trying to save replay of the live but saving replay is not enabled on the instance
3235 /api/v1/videos/live/{id}/sessions:
3236 get:
3237 summary: List live sessions
3238 description: List all sessions created in a particular live
3239 security:
3240 - OAuth2: []
3241 tags:
3242 - Live Videos
3243 parameters:
3244 - $ref: '#/components/parameters/idOrUUID'
3245 responses:
3246 '200':
3247 description: successful operation
3248 content:
3249 application/json:
3250 schema:
3251 type: object
3252 properties:
3253 total:
3254 type: integer
3255 example: 1
3256 data:
3257 type: array
3258 items:
3259 $ref: '#/components/schemas/LiveVideoSessionResponse'
3260 /api/v1/videos/{id}/live-session:
3261 get:
3262 summary: Get live session of a replay
3263 description: If the video is a replay of a live, you can find the associated live session using this endpoint
3264 security:
3265 - OAuth2: []
3266 tags:
3267 - Live Videos
3268 parameters:
3269 - $ref: '#/components/parameters/idOrUUID'
3270 responses:
3271 '200':
3272 description: successful operation
3273 content:
3274 application/json:
3275 schema:
3276 $ref: '#/components/schemas/LiveVideoSessionResponse'
3277
3278 /api/v1/users/me/abuses:
3279 get:
3280 summary: List my abuses
3281 operationId: getMyAbuses
3282 security:
3283 - OAuth2: []
3284 tags:
3285 - Abuses
3286 - My User
3287 parameters:
3288 - name: id
3289 in: query
3290 description: only list the report with this id
3291 schema:
3292 type: integer
3293 - name: state
3294 in: query
3295 schema:
3296 $ref: '#/components/schemas/AbuseStateSet'
3297 - $ref: '#/components/parameters/abusesSort'
3298 - $ref: '#/components/parameters/start'
3299 - $ref: '#/components/parameters/count'
3300 responses:
3301 '200':
3302 description: successful operation
3303 content:
3304 application/json:
3305 schema:
3306 type: object
3307 properties:
3308 total:
3309 type: integer
3310 example: 1
3311 data:
3312 type: array
3313 items:
3314 $ref: '#/components/schemas/Abuse'
3315
3316 /api/v1/abuses:
3317 get:
3318 summary: List abuses
3319 operationId: getAbuses
3320 security:
3321 - OAuth2:
3322 - admin
3323 - moderator
3324 tags:
3325 - Abuses
3326 parameters:
3327 - name: id
3328 in: query
3329 description: only list the report with this id
3330 schema:
3331 type: integer
3332 - name: predefinedReason
3333 in: query
3334 description: predefined reason the listed reports should contain
3335 schema:
3336 $ref: '#/components/schemas/PredefinedAbuseReasons'
3337 - name: search
3338 in: query
3339 description: plain search that will match with video titles, reporter names and more
3340 schema:
3341 type: string
3342 - name: state
3343 in: query
3344 schema:
3345 $ref: '#/components/schemas/AbuseStateSet'
3346 - name: searchReporter
3347 in: query
3348 description: only list reports of a specific reporter
3349 schema:
3350 type: string
3351 - name: searchReportee
3352 description: only list reports of a specific reportee
3353 in: query
3354 schema:
3355 type: string
3356 - name: searchVideo
3357 in: query
3358 description: only list reports of a specific video
3359 schema:
3360 type: string
3361 - name: searchVideoChannel
3362 in: query
3363 description: only list reports of a specific video channel
3364 schema:
3365 type: string
3366 - name: videoIs
3367 in: query
3368 description: only list deleted or blocklisted videos
3369 schema:
3370 type: string
3371 enum:
3372 - 'deleted'
3373 - 'blacklisted'
3374 - name: filter
3375 in: query
3376 description: only list account, comment or video reports
3377 schema:
3378 type: string
3379 enum:
3380 - 'video'
3381 - 'comment'
3382 - 'account'
3383 - $ref: '#/components/parameters/start'
3384 - $ref: '#/components/parameters/count'
3385 - $ref: '#/components/parameters/abusesSort'
3386 responses:
3387 '200':
3388 description: successful operation
3389 content:
3390 application/json:
3391 schema:
3392 type: object
3393 properties:
3394 total:
3395 type: integer
3396 example: 1
3397 data:
3398 type: array
3399 items:
3400 $ref: '#/components/schemas/Abuse'
3401 post:
3402 summary: Report an abuse
3403 security:
3404 - OAuth2: []
3405 tags:
3406 - Abuses
3407 requestBody:
3408 required: true
3409 content:
3410 application/json:
3411 schema:
3412 type: object
3413 properties:
3414 reason:
3415 description: Reason why the user reports this video
3416 type: string
3417 minLength: 2
3418 maxLength: 3000
3419 predefinedReasons:
3420 $ref: '#/components/schemas/PredefinedAbuseReasons'
3421 video:
3422 type: object
3423 properties:
3424 id:
3425 description: Video id to report
3426 allOf:
3427 - $ref: '#/components/schemas/Video/properties/id'
3428 startAt:
3429 type: integer
3430 format: seconds
3431 description: Timestamp in the video that marks the beginning of the report
3432 minimum: 0
3433 endAt:
3434 type: integer
3435 format: seconds
3436 description: Timestamp in the video that marks the ending of the report
3437 minimum: 0
3438 comment:
3439 type: object
3440 properties:
3441 id:
3442 description: Comment id to report
3443 allOf:
3444 - $ref: '#/components/schemas/VideoComment/properties/id'
3445 account:
3446 type: object
3447 properties:
3448 id:
3449 description: Account id to report
3450 type: integer
3451 required:
3452 - reason
3453 responses:
3454 '200':
3455 description: successful operation
3456 content:
3457 application/json:
3458 schema:
3459 type: object
3460 properties:
3461 abuse:
3462 type: object
3463 properties:
3464 id:
3465 $ref: '#/components/schemas/id'
3466 '400':
3467 description: incorrect request parameters
3468
3469 '/api/v1/abuses/{abuseId}':
3470 put:
3471 summary: Update an abuse
3472 security:
3473 - OAuth2:
3474 - admin
3475 - moderator
3476 tags:
3477 - Abuses
3478 parameters:
3479 - $ref: '#/components/parameters/abuseId'
3480 requestBody:
3481 content:
3482 application/json:
3483 schema:
3484 type: object
3485 properties:
3486 state:
3487 $ref: '#/components/schemas/AbuseStateSet'
3488 moderationComment:
3489 type: string
3490 description: Update the report comment visible only to the moderation team
3491 minLength: 2
3492 maxLength: 3000
3493 responses:
3494 '204':
3495 description: successful operation
3496 '404':
3497 description: abuse not found
3498 delete:
3499 tags:
3500 - Abuses
3501 summary: Delete an abuse
3502 security:
3503 - OAuth2:
3504 - admin
3505 - moderator
3506 parameters:
3507 - $ref: '#/components/parameters/abuseId'
3508 responses:
3509 '204':
3510 description: successful operation
3511 '404':
3512 description: block not found
3513
3514 '/api/v1/abuses/{abuseId}/messages':
3515 get:
3516 summary: List messages of an abuse
3517 security:
3518 - OAuth2: []
3519 tags:
3520 - Abuses
3521 parameters:
3522 - $ref: '#/components/parameters/abuseId'
3523 responses:
3524 '200':
3525 description: successful operation
3526 content:
3527 application/json:
3528 schema:
3529 type: object
3530 properties:
3531 total:
3532 type: integer
3533 example: 1
3534 data:
3535 type: array
3536 items:
3537 $ref: '#/components/schemas/AbuseMessage'
3538 post:
3539 summary: Add message to an abuse
3540 security:
3541 - OAuth2: []
3542 tags:
3543 - Abuses
3544 parameters:
3545 - $ref: '#/components/parameters/abuseId'
3546 requestBody:
3547 required: true
3548 content:
3549 application/json:
3550 schema:
3551 type: object
3552 properties:
3553 message:
3554 description: Message to send
3555 type: string
3556 minLength: 2
3557 maxLength: 3000
3558 required:
3559 - message
3560 responses:
3561 '200':
3562 description: successful operation
3563 '400':
3564 description: incorrect request parameters
3565
3566 '/api/v1/abuses/{abuseId}/messages/{abuseMessageId}':
3567 delete:
3568 summary: Delete an abuse message
3569 security:
3570 - OAuth2: []
3571 tags:
3572 - Abuses
3573 parameters:
3574 - $ref: '#/components/parameters/abuseId'
3575 - $ref: '#/components/parameters/abuseMessageId'
3576 responses:
3577 '204':
3578 description: successful operation
3579
3580 '/api/v1/videos/{id}/blacklist':
3581 post:
3582 summary: Block a video
3583 operationId: addVideoBlock
3584 security:
3585 - OAuth2:
3586 - admin
3587 - moderator
3588 tags:
3589 - Video Blocks
3590 parameters:
3591 - $ref: '#/components/parameters/idOrUUID'
3592 responses:
3593 '204':
3594 description: successful operation
3595 delete:
3596 summary: Unblock a video by its id
3597 operationId: delVideoBlock
3598 security:
3599 - OAuth2:
3600 - admin
3601 - moderator
3602 tags:
3603 - Video Blocks
3604 parameters:
3605 - $ref: '#/components/parameters/idOrUUID'
3606 responses:
3607 '204':
3608 description: successful operation
3609 '404':
3610 description: block not found
3611
3612 /api/v1/videos/blacklist:
3613 get:
3614 tags:
3615 - Video Blocks
3616 summary: List video blocks
3617 operationId: getVideoBlocks
3618 security:
3619 - OAuth2:
3620 - admin
3621 - moderator
3622 parameters:
3623 - name: type
3624 in: query
3625 description: >
3626 list only blocks that match this type:
3627
3628 - `1`: manual block
3629
3630 - `2`: automatic block that needs review
3631 schema:
3632 type: integer
3633 enum:
3634 - 1
3635 - 2
3636 - name: search
3637 in: query
3638 description: plain search that will match with video titles, and more
3639 schema:
3640 type: string
3641 - $ref: '#/components/parameters/start'
3642 - $ref: '#/components/parameters/count'
3643 - $ref: '#/components/parameters/blacklistsSort'
3644 responses:
3645 '200':
3646 description: successful operation
3647 content:
3648 application/json:
3649 schema:
3650 type: object
3651 properties:
3652 total:
3653 type: integer
3654 example: 1
3655 data:
3656 type: array
3657 items:
3658 $ref: '#/components/schemas/VideoBlacklist'
3659
3660 /api/v1/videos/{id}/captions:
3661 get:
3662 summary: List captions of a video
3663 operationId: getVideoCaptions
3664 tags:
3665 - Video Captions
3666 parameters:
3667 - $ref: '#/components/parameters/idOrUUID'
3668 responses:
3669 '200':
3670 description: successful operation
3671 content:
3672 application/json:
3673 schema:
3674 type: object
3675 properties:
3676 total:
3677 type: integer
3678 example: 1
3679 data:
3680 type: array
3681 items:
3682 $ref: '#/components/schemas/VideoCaption'
3683
3684 /api/v1/videos/{id}/captions/{captionLanguage}:
3685 put:
3686 summary: Add or replace a video caption
3687 operationId: addVideoCaption
3688 security:
3689 - OAuth2:
3690 - user
3691 tags:
3692 - Video Captions
3693 parameters:
3694 - $ref: '#/components/parameters/idOrUUID'
3695 - $ref: '#/components/parameters/captionLanguage'
3696 requestBody:
3697 content:
3698 multipart/form-data:
3699 schema:
3700 type: object
3701 properties:
3702 captionfile:
3703 description: The file to upload.
3704 type: string
3705 format: binary
3706 encoding:
3707 captionfile:
3708 contentType: text/vtt, application/x-subrip, text/plain
3709 responses:
3710 '204':
3711 description: successful operation
3712 '404':
3713 description: video or language not found
3714 delete:
3715 summary: Delete a video caption
3716 operationId: delVideoCaption
3717 security:
3718 - OAuth2:
3719 - user
3720 tags:
3721 - Video Captions
3722 parameters:
3723 - $ref: '#/components/parameters/idOrUUID'
3724 - $ref: '#/components/parameters/captionLanguage'
3725 responses:
3726 '204':
3727 description: successful operation
3728 '404':
3729 description: video or language or caption for that language not found
3730
3731 /api/v1/video-channels:
3732 get:
3733 summary: List video channels
3734 operationId: getVideoChannels
3735 tags:
3736 - Video Channels
3737 parameters:
3738 - $ref: '#/components/parameters/start'
3739 - $ref: '#/components/parameters/count'
3740 - $ref: '#/components/parameters/sort'
3741 responses:
3742 '200':
3743 description: successful operation
3744 content:
3745 application/json:
3746 schema:
3747 $ref: '#/components/schemas/VideoChannelList'
3748 post:
3749 summary: Create a video channel
3750 operationId: addVideoChannel
3751 security:
3752 - OAuth2: []
3753 tags:
3754 - Video Channels
3755 responses:
3756 '200':
3757 description: successful operation
3758 content:
3759 application/json:
3760 schema:
3761 type: object
3762 properties:
3763 videoChannel:
3764 type: object
3765 properties:
3766 id:
3767 $ref: '#/components/schemas/id'
3768 requestBody:
3769 content:
3770 application/json:
3771 schema:
3772 $ref: '#/components/schemas/VideoChannelCreate'
3773
3774 '/api/v1/video-channels/{channelHandle}':
3775 get:
3776 summary: Get a video channel
3777 operationId: getVideoChannel
3778 tags:
3779 - Video Channels
3780 parameters:
3781 - $ref: '#/components/parameters/channelHandle'
3782 responses:
3783 '200':
3784 description: successful operation
3785 content:
3786 application/json:
3787 schema:
3788 $ref: '#/components/schemas/VideoChannel'
3789 put:
3790 summary: Update a video channel
3791 operationId: putVideoChannel
3792 security:
3793 - OAuth2: []
3794 tags:
3795 - Video Channels
3796 parameters:
3797 - $ref: '#/components/parameters/channelHandle'
3798 responses:
3799 '204':
3800 description: successful operation
3801 requestBody:
3802 content:
3803 application/json:
3804 schema:
3805 $ref: '#/components/schemas/VideoChannelUpdate'
3806 delete:
3807 summary: Delete a video channel
3808 operationId: delVideoChannel
3809 security:
3810 - OAuth2: []
3811 tags:
3812 - Video Channels
3813 parameters:
3814 - $ref: '#/components/parameters/channelHandle'
3815 responses:
3816 '204':
3817 description: successful operation
3818
3819 '/api/v1/video-channels/{channelHandle}/videos':
3820 get:
3821 summary: List videos of a video channel
3822 operationId: getVideoChannelVideos
3823 tags:
3824 - Video
3825 - Video Channels
3826 parameters:
3827 - $ref: '#/components/parameters/channelHandle'
3828 - $ref: '#/components/parameters/categoryOneOf'
3829 - $ref: '#/components/parameters/isLive'
3830 - $ref: '#/components/parameters/tagsOneOf'
3831 - $ref: '#/components/parameters/tagsAllOf'
3832 - $ref: '#/components/parameters/licenceOneOf'
3833 - $ref: '#/components/parameters/languageOneOf'
3834 - $ref: '#/components/parameters/nsfw'
3835 - $ref: '#/components/parameters/isLocal'
3836 - $ref: '#/components/parameters/include'
3837 - $ref: '#/components/parameters/privacyOneOf'
3838 - $ref: '#/components/parameters/hasHLSFiles'
3839 - $ref: '#/components/parameters/hasWebtorrentFiles'
3840 - $ref: '#/components/parameters/skipCount'
3841 - $ref: '#/components/parameters/start'
3842 - $ref: '#/components/parameters/count'
3843 - $ref: '#/components/parameters/videosSort'
3844 - $ref: '#/components/parameters/excludeAlreadyWatched'
3845 responses:
3846 '200':
3847 description: successful operation
3848 content:
3849 application/json:
3850 schema:
3851 $ref: '#/components/schemas/VideoListResponse'
3852
3853 '/api/v1/video-channels/{channelHandle}/video-playlists':
3854 get:
3855 summary: List playlists of a channel
3856 tags:
3857 - Video Playlists
3858 - Video Channels
3859 parameters:
3860 - $ref: '#/components/parameters/channelHandle'
3861 - $ref: '#/components/parameters/start'
3862 - $ref: '#/components/parameters/count'
3863 - $ref: '#/components/parameters/sort'
3864 - $ref: '#/components/parameters/videoPlaylistType'
3865 responses:
3866 '200':
3867 description: successful operation
3868 content:
3869 application/json:
3870 schema:
3871 type: object
3872 properties:
3873 total:
3874 type: integer
3875 example: 1
3876 data:
3877 type: array
3878 items:
3879 $ref: '#/components/schemas/VideoPlaylist'
3880
3881 '/api/v1/video-channels/{channelHandle}/followers':
3882 get:
3883 tags:
3884 - Video Channels
3885 summary: 'List followers of a video channel'
3886 security:
3887 - OAuth2: []
3888 operationId: getVideoChannelFollowers
3889 parameters:
3890 - $ref: '#/components/parameters/channelHandle'
3891 - $ref: '#/components/parameters/start'
3892 - $ref: '#/components/parameters/count'
3893 - $ref: '#/components/parameters/followersSort'
3894 - $ref: '#/components/parameters/search'
3895 responses:
3896 '200':
3897 description: successful operation
3898 content:
3899 application/json:
3900 schema:
3901 type: object
3902 properties:
3903 total:
3904 type: integer
3905 example: 1
3906 data:
3907 type: array
3908 items:
3909 $ref: '#/components/schemas/Follow'
3910
3911 '/api/v1/video-channels/{channelHandle}/avatar/pick':
3912 post:
3913 summary: Update channel avatar
3914 security:
3915 - OAuth2: []
3916 tags:
3917 - Video Channels
3918 parameters:
3919 - $ref: '#/components/parameters/channelHandle'
3920 responses:
3921 '200':
3922 description: successful operation
3923 content:
3924 application/json:
3925 schema:
3926 type: object
3927 properties:
3928 avatars:
3929 type: array
3930 items:
3931 $ref: '#/components/schemas/ActorImage'
3932 '413':
3933 description: image file too large
3934 headers:
3935 X-File-Maximum-Size:
3936 schema:
3937 type: string
3938 format: Nginx size
3939 description: Maximum file size for the avatar
3940 requestBody:
3941 content:
3942 multipart/form-data:
3943 schema:
3944 type: object
3945 properties:
3946 avatarfile:
3947 description: The file to upload.
3948 type: string
3949 format: binary
3950 encoding:
3951 avatarfile:
3952 contentType: image/png, image/jpeg
3953
3954 '/api/v1/video-channels/{channelHandle}/avatar':
3955 delete:
3956 summary: Delete channel avatar
3957 security:
3958 - OAuth2: []
3959 tags:
3960 - Video Channels
3961 parameters:
3962 - $ref: '#/components/parameters/channelHandle'
3963 responses:
3964 '204':
3965 description: successful operation
3966
3967 '/api/v1/video-channels/{channelHandle}/banner/pick':
3968 post:
3969 summary: Update channel banner
3970 security:
3971 - OAuth2: []
3972 tags:
3973 - Video Channels
3974 parameters:
3975 - $ref: '#/components/parameters/channelHandle'
3976 responses:
3977 '200':
3978 description: successful operation
3979 content:
3980 application/json:
3981 schema:
3982 type: object
3983 properties:
3984 banners:
3985 type: array
3986 items:
3987 $ref: '#/components/schemas/ActorImage'
3988 '413':
3989 description: image file too large
3990 headers:
3991 X-File-Maximum-Size:
3992 schema:
3993 type: string
3994 format: Nginx size
3995 description: Maximum file size for the banner
3996 requestBody:
3997 content:
3998 multipart/form-data:
3999 schema:
4000 type: object
4001 properties:
4002 bannerfile:
4003 description: The file to upload.
4004 type: string
4005 format: binary
4006 encoding:
4007 bannerfile:
4008 contentType: image/png, image/jpeg
4009
4010 '/api/v1/video-channels/{channelHandle}/banner':
4011 delete:
4012 summary: Delete channel banner
4013 security:
4014 - OAuth2: []
4015 tags:
4016 - Video Channels
4017 parameters:
4018 - $ref: '#/components/parameters/channelHandle'
4019 responses:
4020 '204':
4021 description: successful operation
4022
4023 '/api/v1/video-channels/{channelHandle}/import-videos':
4024 post:
4025 summary: Import videos in channel
4026 description: Import a remote channel/playlist videos into a channel
4027 security:
4028 - OAuth2: []
4029 tags:
4030 - Video Channels
4031 - Channels Sync
4032 parameters:
4033 - $ref: '#/components/parameters/channelHandle'
4034 requestBody:
4035 content:
4036 application/json:
4037 schema:
4038 $ref: '#/components/schemas/ImportVideosInChannelCreate'
4039 responses:
4040 '204':
4041 description: successful operation
4042
4043 '/api/v1/video-channel-syncs':
4044 post:
4045 summary: Create a synchronization for a video channel
4046 operationId: addVideoChannelSync
4047 security:
4048 - OAuth2: []
4049 tags:
4050 - Channels Sync
4051 requestBody:
4052 content:
4053 application/json:
4054 schema:
4055 $ref: '#/components/schemas/VideoChannelSyncCreate'
4056 responses:
4057 '200':
4058 description: successful operation
4059 content:
4060 application/json:
4061 schema:
4062 type: object
4063 properties:
4064 videoChannelSync:
4065 $ref: "#/components/schemas/VideoChannelSync"
4066
4067 '/api/v1/video-channel-syncs/{channelSyncId}':
4068 delete:
4069 summary: Delete a video channel synchronization
4070 operationId: delVideoChannelSync
4071 security:
4072 - OAuth2: []
4073 tags:
4074 - Channels Sync
4075 parameters:
4076 - $ref: '#/components/parameters/channelSyncId'
4077 responses:
4078 '204':
4079 description: successful operation
4080
4081 '/api/v1/video-channel-syncs/{channelSyncId}/sync':
4082 post:
4083 summary: Triggers the channel synchronization job, fetching all the videos from the remote channel
4084 operationId: triggerVideoChannelSync
4085 security:
4086 - OAuth2: []
4087 tags:
4088 - Channels Sync
4089 parameters:
4090 - $ref: '#/components/parameters/channelSyncId'
4091 responses:
4092 '204':
4093 description: successful operation
4094
4095
4096 /api/v1/video-playlists/privacies:
4097 get:
4098 summary: List available playlist privacy policies
4099 operationId: getPlaylistPrivacyPolicies
4100 tags:
4101 - Video Playlists
4102 responses:
4103 '200':
4104 description: successful operation
4105 content:
4106 application/json:
4107 schema:
4108 type: array
4109 items:
4110 type: string
4111 examples:
4112 nightly:
4113 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
4114
4115 /api/v1/video-playlists:
4116 get:
4117 summary: List video playlists
4118 operationId: getPlaylists
4119 tags:
4120 - Video Playlists
4121 parameters:
4122 - $ref: '#/components/parameters/start'
4123 - $ref: '#/components/parameters/count'
4124 - $ref: '#/components/parameters/sort'
4125 - $ref: '#/components/parameters/videoPlaylistType'
4126 responses:
4127 '200':
4128 description: successful operation
4129 content:
4130 application/json:
4131 schema:
4132 type: object
4133 properties:
4134 total:
4135 type: integer
4136 example: 1
4137 data:
4138 type: array
4139 items:
4140 $ref: '#/components/schemas/VideoPlaylist'
4141 post:
4142 summary: Create a video playlist
4143 description: If the video playlist is set as public, `videoChannelId` is mandatory.
4144 operationId: addPlaylist
4145 security:
4146 - OAuth2: []
4147 tags:
4148 - Video Playlists
4149 responses:
4150 '200':
4151 description: successful operation
4152 content:
4153 application/json:
4154 schema:
4155 type: object
4156 properties:
4157 videoPlaylist:
4158 type: object
4159 properties:
4160 id:
4161 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4162 uuid:
4163 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
4164 shortUUID:
4165 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
4166 requestBody:
4167 content:
4168 multipart/form-data:
4169 schema:
4170 type: object
4171 properties:
4172 displayName:
4173 description: Video playlist display name
4174 type: string
4175 minLength: 1
4176 maxLength: 120
4177 thumbnailfile:
4178 description: Video playlist thumbnail file
4179 type: string
4180 format: binary
4181 privacy:
4182 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4183 description:
4184 description: Video playlist description
4185 type: string
4186 minLength: 3
4187 maxLength: 1000
4188 videoChannelId:
4189 allOf:
4190 - $ref: '#/components/schemas/id'
4191 description: Video channel in which the playlist will be published
4192 required:
4193 - displayName
4194 encoding:
4195 thumbnailfile:
4196 contentType: image/jpeg
4197
4198 /api/v1/video-playlists/{playlistId}:
4199 get:
4200 summary: Get a video playlist
4201 tags:
4202 - Video Playlists
4203 parameters:
4204 - $ref: '#/components/parameters/playlistId'
4205 responses:
4206 '200':
4207 description: successful operation
4208 content:
4209 application/json:
4210 schema:
4211 $ref: '#/components/schemas/VideoPlaylist'
4212 put:
4213 summary: Update a video playlist
4214 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
4215 security:
4216 - OAuth2: []
4217 tags:
4218 - Video Playlists
4219 responses:
4220 '204':
4221 description: successful operation
4222 parameters:
4223 - $ref: '#/components/parameters/playlistId'
4224 requestBody:
4225 content:
4226 multipart/form-data:
4227 schema:
4228 type: object
4229 properties:
4230 displayName:
4231 description: Video playlist display name
4232 type: string
4233 minLength: 1
4234 maxLength: 120
4235 thumbnailfile:
4236 description: Video playlist thumbnail file
4237 type: string
4238 format: binary
4239 privacy:
4240 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4241 description:
4242 description: Video playlist description
4243 type: string
4244 videoChannelId:
4245 allOf:
4246 - $ref: '#/components/schemas/id'
4247 description: Video channel in which the playlist will be published
4248 encoding:
4249 thumbnailfile:
4250 contentType: image/jpeg
4251 delete:
4252 summary: Delete a video playlist
4253 security:
4254 - OAuth2: []
4255 tags:
4256 - Video Playlists
4257 parameters:
4258 - $ref: '#/components/parameters/playlistId'
4259 responses:
4260 '204':
4261 description: successful operation
4262
4263 /api/v1/video-playlists/{playlistId}/videos:
4264 get:
4265 summary: 'List videos of a playlist'
4266 operationId: getVideoPlaylistVideos
4267 tags:
4268 - Videos
4269 - Video Playlists
4270 parameters:
4271 - $ref: '#/components/parameters/playlistId'
4272 - $ref: '#/components/parameters/start'
4273 - $ref: '#/components/parameters/count'
4274 responses:
4275 '200':
4276 description: successful operation
4277 content:
4278 application/json:
4279 schema:
4280 $ref: '#/components/schemas/VideoListResponse'
4281 post:
4282 summary: Add a video in a playlist
4283 operationId: addVideoPlaylistVideo
4284 security:
4285 - OAuth2: []
4286 tags:
4287 - Videos
4288 - Video Playlists
4289 parameters:
4290 - $ref: '#/components/parameters/playlistId'
4291 responses:
4292 '200':
4293 description: successful operation
4294 content:
4295 application/json:
4296 schema:
4297 type: object
4298 properties:
4299 videoPlaylistElement:
4300 type: object
4301 properties:
4302 id:
4303 type: integer
4304 example: 2
4305 requestBody:
4306 content:
4307 application/json:
4308 schema:
4309 type: object
4310 properties:
4311 videoId:
4312 oneOf:
4313 - $ref: '#/components/schemas/Video/properties/uuid'
4314 - $ref: '#/components/schemas/Video/properties/id'
4315 description: Video to add in the playlist
4316 startTimestamp:
4317 type: integer
4318 format: seconds
4319 description: Start the video at this specific timestamp
4320 stopTimestamp:
4321 type: integer
4322 format: seconds
4323 description: Stop the video at this specific timestamp
4324 required:
4325 - videoId
4326
4327 /api/v1/video-playlists/{playlistId}/videos/reorder:
4328 post:
4329 summary: 'Reorder a playlist'
4330 operationId: reorderVideoPlaylist
4331 security:
4332 - OAuth2: []
4333 tags:
4334 - Video Playlists
4335 parameters:
4336 - $ref: '#/components/parameters/playlistId'
4337 responses:
4338 '204':
4339 description: successful operation
4340 requestBody:
4341 content:
4342 application/json:
4343 schema:
4344 type: object
4345 properties:
4346 startPosition:
4347 type: integer
4348 description: 'Start position of the element to reorder'
4349 minimum: 1
4350 insertAfterPosition:
4351 type: integer
4352 description: 'New position for the block to reorder, to add the block before the first element'
4353 minimum: 0
4354 reorderLength:
4355 type: integer
4356 description: 'How many element from `startPosition` to reorder'
4357 minimum: 1
4358 required:
4359 - startPosition
4360 - insertAfterPosition
4361
4362 /api/v1/video-playlists/{playlistId}/videos/{playlistElementId}:
4363 put:
4364 summary: Update a playlist element
4365 operationId: putVideoPlaylistVideo
4366 security:
4367 - OAuth2: []
4368 tags:
4369 - Video Playlists
4370 parameters:
4371 - $ref: '#/components/parameters/playlistId'
4372 - $ref: '#/components/parameters/playlistElementId'
4373 responses:
4374 '204':
4375 description: successful operation
4376 requestBody:
4377 content:
4378 application/json:
4379 schema:
4380 type: object
4381 properties:
4382 startTimestamp:
4383 type: integer
4384 format: seconds
4385 description: Start the video at this specific timestamp
4386 stopTimestamp:
4387 type: integer
4388 format: seconds
4389 description: Stop the video at this specific timestamp
4390 delete:
4391 summary: Delete an element from a playlist
4392 operationId: delVideoPlaylistVideo
4393 security:
4394 - OAuth2: []
4395 tags:
4396 - Video Playlists
4397 parameters:
4398 - $ref: '#/components/parameters/playlistId'
4399 - $ref: '#/components/parameters/playlistElementId'
4400 responses:
4401 '204':
4402 description: successful operation
4403
4404 '/api/v1/users/me/video-playlists/videos-exist':
4405 get:
4406 summary: Check video exists in my playlists
4407 security:
4408 - OAuth2: []
4409 tags:
4410 - Video Playlists
4411 parameters:
4412 - name: videoIds
4413 in: query
4414 required: true
4415 description: The video ids to check
4416 schema:
4417 type: array
4418 items:
4419 $ref: '#/components/schemas/Video/properties/id'
4420 responses:
4421 '200':
4422 description: successful operation
4423 content:
4424 application/json:
4425 schema:
4426 type: object
4427 properties:
4428 videoId:
4429 type: array
4430 items:
4431 type: object
4432 properties:
4433 playlistElementId:
4434 type: integer
4435 playlistId:
4436 type: integer
4437 startTimestamp:
4438 type: integer
4439 format: seconds
4440 stopTimestamp:
4441 type: integer
4442
4443 '/api/v1/accounts/{name}/video-playlists':
4444 get:
4445 summary: List playlists of an account
4446 tags:
4447 - Video Playlists
4448 - Accounts
4449 parameters:
4450 - $ref: '#/components/parameters/name'
4451 - $ref: '#/components/parameters/start'
4452 - $ref: '#/components/parameters/count'
4453 - $ref: '#/components/parameters/sort'
4454 - $ref: '#/components/parameters/search'
4455 - $ref: '#/components/parameters/videoPlaylistType'
4456 responses:
4457 '200':
4458 description: successful operation
4459 content:
4460 application/json:
4461 schema:
4462 type: object
4463 properties:
4464 total:
4465 type: integer
4466 example: 1
4467 data:
4468 type: array
4469 items:
4470 $ref: '#/components/schemas/VideoPlaylist'
4471
4472 '/api/v1/accounts/{name}/video-channels':
4473 get:
4474 summary: List video channels of an account
4475 tags:
4476 - Video Channels
4477 - Accounts
4478 parameters:
4479 - $ref: '#/components/parameters/name'
4480 - name: withStats
4481 in: query
4482 description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
4483 schema:
4484 type: boolean
4485 - $ref: '#/components/parameters/start'
4486 - $ref: '#/components/parameters/count'
4487 - $ref: '#/components/parameters/sort'
4488 responses:
4489 '200':
4490 description: successful operation
4491 content:
4492 application/json:
4493 schema:
4494 $ref: '#/components/schemas/VideoChannelList'
4495
4496 '/api/v1/accounts/{name}/video-channel-syncs':
4497 get:
4498 summary: List the synchronizations of video channels of an account
4499 tags:
4500 - Video Channels
4501 - Channels Sync
4502 - Accounts
4503 parameters:
4504 - $ref: '#/components/parameters/name'
4505 - $ref: '#/components/parameters/start'
4506 - $ref: '#/components/parameters/count'
4507 - $ref: '#/components/parameters/sort'
4508 responses:
4509 '200':
4510 description: successful operation
4511 content:
4512 application/json:
4513 schema:
4514 $ref: '#/components/schemas/VideoChannelSyncList'
4515
4516 '/api/v1/accounts/{name}/ratings':
4517 get:
4518 summary: List ratings of an account
4519 security:
4520 - OAuth2: []
4521 tags:
4522 - Accounts
4523 parameters:
4524 - $ref: '#/components/parameters/name'
4525 - $ref: '#/components/parameters/start'
4526 - $ref: '#/components/parameters/count'
4527 - $ref: '#/components/parameters/sort'
4528 - name: rating
4529 in: query
4530 required: false
4531 description: Optionally filter which ratings to retrieve
4532 schema:
4533 type: string
4534 enum:
4535 - like
4536 - dislike
4537 responses:
4538 '200':
4539 description: successful operation
4540 content:
4541 application/json:
4542 schema:
4543 type: array
4544 items:
4545 $ref: '#/components/schemas/VideoRating'
4546
4547 '/api/v1/videos/{id}/comment-threads':
4548 get:
4549 summary: List threads of a video
4550 tags:
4551 - Video Comments
4552 parameters:
4553 - $ref: '#/components/parameters/idOrUUID'
4554 - $ref: '#/components/parameters/start'
4555 - $ref: '#/components/parameters/count'
4556 - $ref: '#/components/parameters/commentsSort'
4557 responses:
4558 '200':
4559 description: successful operation
4560 content:
4561 application/json:
4562 schema:
4563 $ref: '#/components/schemas/CommentThreadResponse'
4564 post:
4565 summary: Create a thread
4566 security:
4567 - OAuth2: []
4568 tags:
4569 - Video Comments
4570 parameters:
4571 - $ref: '#/components/parameters/idOrUUID'
4572 responses:
4573 '200':
4574 description: successful operation
4575 content:
4576 application/json:
4577 schema:
4578 $ref: '#/components/schemas/CommentThreadPostResponse'
4579 '404':
4580 description: video does not exist
4581 requestBody:
4582 content:
4583 application/json:
4584 schema:
4585 type: object
4586 properties:
4587 text:
4588 allOf:
4589 - $ref: '#/components/schemas/VideoComment/properties/text'
4590 format: markdown
4591 maxLength: 10000
4592 required:
4593 - text
4594
4595 '/api/v1/videos/{id}/comment-threads/{threadId}':
4596 get:
4597 summary: Get a thread
4598 tags:
4599 - Video Comments
4600 parameters:
4601 - $ref: '#/components/parameters/idOrUUID'
4602 - $ref: '#/components/parameters/threadId'
4603 responses:
4604 '200':
4605 description: successful operation
4606 content:
4607 application/json:
4608 schema:
4609 $ref: '#/components/schemas/VideoCommentThreadTree'
4610
4611 '/api/v1/videos/{id}/comments/{commentId}':
4612 post:
4613 summary: Reply to a thread of a video
4614 security:
4615 - OAuth2: []
4616 tags:
4617 - Video Comments
4618 parameters:
4619 - $ref: '#/components/parameters/idOrUUID'
4620 - $ref: '#/components/parameters/commentId'
4621 responses:
4622 '200':
4623 description: successful operation
4624 content:
4625 application/json:
4626 schema:
4627 $ref: '#/components/schemas/CommentThreadPostResponse'
4628 '404':
4629 description: thread or video does not exist
4630 requestBody:
4631 content:
4632 application/json:
4633 schema:
4634 type: object
4635 properties:
4636 text:
4637 allOf:
4638 - $ref: '#/components/schemas/VideoComment/properties/text'
4639 format: markdown
4640 maxLength: 10000
4641 required:
4642 - text
4643 delete:
4644 summary: Delete a comment or a reply
4645 security:
4646 - OAuth2: []
4647 tags:
4648 - Video Comments
4649 parameters:
4650 - $ref: '#/components/parameters/idOrUUID'
4651 - $ref: '#/components/parameters/commentId'
4652 responses:
4653 '204':
4654 description: successful operation
4655 '403':
4656 description: cannot remove comment of another user
4657 '404':
4658 description: comment or video does not exist
4659 '409':
4660 description: comment is already deleted
4661
4662 '/api/v1/videos/{id}/rate':
4663 put:
4664 summary: Like/dislike a video
4665 security:
4666 - OAuth2: []
4667 tags:
4668 - Video Rates
4669 parameters:
4670 - $ref: '#/components/parameters/idOrUUID'
4671 requestBody:
4672 content:
4673 application/json:
4674 schema:
4675 type: object
4676 properties:
4677 rating:
4678 type: string
4679 enum:
4680 - like
4681 - dislike
4682 required:
4683 - rating
4684 responses:
4685 '204':
4686 description: successful operation
4687 '404':
4688 description: video does not exist
4689
4690 '/api/v1/videos/{id}/hls':
4691 delete:
4692 summary: Delete video HLS files
4693 security:
4694 - OAuth2:
4695 - admin
4696 tags:
4697 - Video Files
4698 operationId: delVideoHLS
4699 parameters:
4700 - $ref: '#/components/parameters/idOrUUID'
4701 responses:
4702 '204':
4703 description: successful operation
4704 '404':
4705 description: video does not exist
4706 '/api/v1/videos/{id}/webtorrent':
4707 delete:
4708 summary: Delete video WebTorrent files
4709 security:
4710 - OAuth2:
4711 - admin
4712 tags:
4713 - Video Files
4714 operationId: delVideoWebTorrent
4715 parameters:
4716 - $ref: '#/components/parameters/idOrUUID'
4717 responses:
4718 '204':
4719 description: successful operation
4720 '404':
4721 description: video does not exist
4722
4723 '/api/v1/videos/{id}/transcoding':
4724 post:
4725 summary: Create a transcoding job
4726 security:
4727 - OAuth2:
4728 - admin
4729 tags:
4730 - Video Transcoding
4731 operationId: createVideoTranscoding
4732 parameters:
4733 - $ref: '#/components/parameters/idOrUUID'
4734 requestBody:
4735 content:
4736 application/json:
4737 schema:
4738 type: object
4739 properties:
4740 transcodingType:
4741 type: string
4742 enum:
4743 - hls
4744 - webtorrent
4745 required:
4746 - transcodingType
4747 responses:
4748 '204':
4749 description: successful operation
4750 '404':
4751 description: video does not exist
4752
4753 /api/v1/search/videos:
4754 get:
4755 tags:
4756 - Search
4757 summary: Search videos
4758 operationId: searchVideos
4759 parameters:
4760 - name: search
4761 in: query
4762 required: true
4763 allowEmptyValue: false
4764 description: >
4765 String to search. If the user can make a remote URI search, and the string is an URI then the
4766 PeerTube instance will fetch the remote object and add it to its database. Then,
4767 you can use the REST API to fetch the complete video information and interact with it.
4768 schema:
4769 type: string
4770 - $ref: '#/components/parameters/categoryOneOf'
4771 - $ref: '#/components/parameters/isLive'
4772 - $ref: '#/components/parameters/tagsOneOf'
4773 - $ref: '#/components/parameters/tagsAllOf'
4774 - $ref: '#/components/parameters/licenceOneOf'
4775 - $ref: '#/components/parameters/languageOneOf'
4776 - $ref: '#/components/parameters/nsfw'
4777 - $ref: '#/components/parameters/isLocal'
4778 - $ref: '#/components/parameters/include'
4779 - $ref: '#/components/parameters/privacyOneOf'
4780 - $ref: '#/components/parameters/uuids'
4781 - $ref: '#/components/parameters/hasHLSFiles'
4782 - $ref: '#/components/parameters/hasWebtorrentFiles'
4783 - $ref: '#/components/parameters/skipCount'
4784 - $ref: '#/components/parameters/start'
4785 - $ref: '#/components/parameters/count'
4786 - $ref: '#/components/parameters/searchTarget'
4787 - $ref: '#/components/parameters/videosSearchSort'
4788 - $ref: '#/components/parameters/excludeAlreadyWatched'
4789 - name: startDate
4790 in: query
4791 description: Get videos that are published after this date
4792 schema:
4793 type: string
4794 format: date-time
4795 - name: endDate
4796 in: query
4797 description: Get videos that are published before this date
4798 schema:
4799 type: string
4800 format: date-time
4801 - name: originallyPublishedStartDate
4802 in: query
4803 description: Get videos that are originally published after this date
4804 schema:
4805 type: string
4806 format: date-time
4807 - name: originallyPublishedEndDate
4808 in: query
4809 description: Get videos that are originally published before this date
4810 schema:
4811 type: string
4812 format: date-time
4813 - name: durationMin
4814 in: query
4815 description: Get videos that have this minimum duration
4816 schema:
4817 type: integer
4818 - name: durationMax
4819 in: query
4820 description: Get videos that have this maximum duration
4821 schema:
4822 type: integer
4823 callbacks:
4824 'searchTarget === search-index':
4825 $ref: '#/components/callbacks/searchIndex'
4826 responses:
4827 '200':
4828 description: successful operation
4829 content:
4830 application/json:
4831 schema:
4832 $ref: '#/components/schemas/VideoListResponse'
4833 '500':
4834 description: search index unavailable
4835
4836 /api/v1/search/video-channels:
4837 get:
4838 tags:
4839 - Search
4840 summary: Search channels
4841 operationId: searchChannels
4842 parameters:
4843 - name: search
4844 in: query
4845 required: true
4846 description: >
4847 String to search. If the user can make a remote URI search, and the string is an URI then the
4848 PeerTube instance will fetch the remote object and add it to its database. Then,
4849 you can use the REST API to fetch the complete channel information and interact with it.
4850 schema:
4851 type: string
4852 - $ref: '#/components/parameters/start'
4853 - $ref: '#/components/parameters/count'
4854 - $ref: '#/components/parameters/searchTarget'
4855 - $ref: '#/components/parameters/sort'
4856 callbacks:
4857 'searchTarget === search-index':
4858 $ref: '#/components/callbacks/searchIndex'
4859 responses:
4860 '200':
4861 description: successful operation
4862 content:
4863 application/json:
4864 schema:
4865 $ref: '#/components/schemas/VideoChannelList'
4866 '500':
4867 description: search index unavailable
4868
4869 /api/v1/search/video-playlists:
4870 get:
4871 tags:
4872 - Search
4873 summary: Search playlists
4874 operationId: searchPlaylists
4875 parameters:
4876 - name: search
4877 in: query
4878 required: true
4879 description: >
4880 String to search. If the user can make a remote URI search, and the string is an URI then the
4881 PeerTube instance will fetch the remote object and add it to its database. Then,
4882 you can use the REST API to fetch the complete playlist information and interact with it.
4883 schema:
4884 type: string
4885 - $ref: '#/components/parameters/start'
4886 - $ref: '#/components/parameters/count'
4887 - $ref: '#/components/parameters/searchTarget'
4888 - $ref: '#/components/parameters/sort'
4889 callbacks:
4890 'searchTarget === search-index':
4891 $ref: '#/components/callbacks/searchIndex'
4892 responses:
4893 '200':
4894 description: successful operation
4895 content:
4896 application/json:
4897 schema:
4898 type: object
4899 properties:
4900 total:
4901 type: integer
4902 example: 1
4903 data:
4904 type: array
4905 items:
4906 $ref: '#/components/schemas/VideoPlaylist'
4907 '500':
4908 description: search index unavailable
4909
4910 /api/v1/blocklist/status:
4911 get:
4912 tags:
4913 - Account Blocks
4914 - Server Blocks
4915 summary: Get block status of accounts/hosts
4916 parameters:
4917 -
4918 name: 'accounts'
4919 in: query
4920 description: 'Check if these accounts are blocked'
4921 example: [ 'goofy@example.com', 'donald@example.com' ]
4922 schema:
4923 type: array
4924 items:
4925 type: string
4926 -
4927 name: 'hosts'
4928 in: query
4929 description: 'Check if these hosts are blocked'
4930 example: [ 'example.com' ]
4931 schema:
4932 type: array
4933 items:
4934 type: string
4935 responses:
4936 '200':
4937 description: successful operation
4938 content:
4939 'application/json':
4940 schema:
4941 $ref: '#/components/schemas/BlockStatus'
4942
4943 /api/v1/server/blocklist/accounts:
4944 get:
4945 tags:
4946 - Account Blocks
4947 summary: List account blocks
4948 security:
4949 - OAuth2:
4950 - admin
4951 parameters:
4952 - $ref: '#/components/parameters/start'
4953 - $ref: '#/components/parameters/count'
4954 - $ref: '#/components/parameters/sort'
4955 responses:
4956 '200':
4957 description: successful operation
4958 post:
4959 tags:
4960 - Account Blocks
4961 summary: Block an account
4962 security:
4963 - OAuth2:
4964 - admin
4965 requestBody:
4966 content:
4967 application/json:
4968 schema:
4969 type: object
4970 properties:
4971 accountName:
4972 type: string
4973 example: chocobozzz@example.org
4974 description: account to block, in the form `username@domain`
4975 required:
4976 - accountName
4977 responses:
4978 '200':
4979 description: successful operation
4980 '409':
4981 description: self-blocking forbidden
4982
4983 '/api/v1/server/blocklist/accounts/{accountName}':
4984 delete:
4985 tags:
4986 - Account Blocks
4987 summary: Unblock an account by its handle
4988 security:
4989 - OAuth2:
4990 - admin
4991 parameters:
4992 - name: accountName
4993 in: path
4994 required: true
4995 description: account to unblock, in the form `username@domain`
4996 schema:
4997 type: string
4998 responses:
4999 '201':
5000 description: successful operation
5001 '404':
5002 description: account or account block does not exist
5003
5004 /api/v1/server/blocklist/servers:
5005 get:
5006 tags:
5007 - Server Blocks
5008 summary: List server blocks
5009 security:
5010 - OAuth2:
5011 - admin
5012 parameters:
5013 - $ref: '#/components/parameters/start'
5014 - $ref: '#/components/parameters/count'
5015 - $ref: '#/components/parameters/sort'
5016 responses:
5017 '200':
5018 description: successful operation
5019 post:
5020 tags:
5021 - Server Blocks
5022 summary: Block a server
5023 security:
5024 - OAuth2:
5025 - admin
5026 requestBody:
5027 content:
5028 application/json:
5029 schema:
5030 type: object
5031 properties:
5032 host:
5033 type: string
5034 format: hostname
5035 description: server domain to block
5036 required:
5037 - host
5038 responses:
5039 '204':
5040 description: successful operation
5041 '409':
5042 description: self-blocking forbidden
5043
5044 '/api/v1/server/blocklist/servers/{host}':
5045 delete:
5046 tags:
5047 - Server Blocks
5048 summary: Unblock a server by its domain
5049 security:
5050 - OAuth2:
5051 - admin
5052 parameters:
5053 - name: host
5054 in: path
5055 required: true
5056 description: server domain to unblock
5057 schema:
5058 type: string
5059 format: hostname
5060 responses:
5061 '204':
5062 description: successful operation
5063 '404':
5064 description: account block does not exist
5065
5066 /api/v1/server/redundancy/{host}:
5067 put:
5068 tags:
5069 - Instance Redundancy
5070 summary: Update a server redundancy policy
5071 security:
5072 - OAuth2:
5073 - admin
5074 parameters:
5075 - name: host
5076 in: path
5077 required: true
5078 description: server domain to mirror
5079 schema:
5080 type: string
5081 format: hostname
5082 requestBody:
5083 content:
5084 application/json:
5085 schema:
5086 type: object
5087 properties:
5088 redundancyAllowed:
5089 type: boolean
5090 description: allow mirroring of the host's local videos
5091 required:
5092 - redundancyAllowed
5093 responses:
5094 '204':
5095 description: successful operation
5096 '404':
5097 description: server is not already known
5098
5099 /api/v1/server/redundancy/videos:
5100 get:
5101 tags:
5102 - Video Mirroring
5103 summary: List videos being mirrored
5104 operationId: getMirroredVideos
5105 security:
5106 - OAuth2:
5107 - admin
5108 parameters:
5109 - name: target
5110 in: query
5111 required: true
5112 description: direction of the mirror
5113 schema:
5114 type: string
5115 enum:
5116 - my-videos
5117 - remote-videos
5118 - $ref: '#/components/parameters/start'
5119 - $ref: '#/components/parameters/count'
5120 - $ref: '#/components/parameters/videoRedundanciesSort'
5121 responses:
5122 '200':
5123 description: successful operation
5124 content:
5125 application/json:
5126 schema:
5127 type: array
5128 items:
5129 $ref: '#/components/schemas/VideoRedundancy'
5130 post:
5131 tags:
5132 - Video Mirroring
5133 summary: Mirror a video
5134 operationId: putMirroredVideo
5135 security:
5136 - OAuth2:
5137 - admin
5138 requestBody:
5139 content:
5140 application/json:
5141 schema:
5142 type: object
5143 properties:
5144 videoId:
5145 $ref: '#/components/schemas/Video/properties/id'
5146 required:
5147 - videoId
5148 responses:
5149 '204':
5150 description: successful operation
5151 '400':
5152 description: cannot mirror a local video
5153 '404':
5154 description: video does not exist
5155 '409':
5156 description: video is already mirrored
5157
5158 /api/v1/server/redundancy/videos/{redundancyId}:
5159 delete:
5160 tags:
5161 - Video Mirroring
5162 summary: Delete a mirror done on a video
5163 operationId: delMirroredVideo
5164 security:
5165 - OAuth2:
5166 - admin
5167 parameters:
5168 - name: redundancyId
5169 in: path
5170 required: true
5171 description: id of an existing redundancy on a video
5172 schema:
5173 type: string
5174 responses:
5175 '204':
5176 description: successful operation
5177 '404':
5178 description: video redundancy not found
5179
5180 /api/v1/server/stats:
5181 get:
5182 tags:
5183 - Stats
5184 summary: Get instance stats
5185 description: Get instance public statistics. This endpoint is cached.
5186 operationId: getInstanceStats
5187 responses:
5188 '200':
5189 description: successful operation
5190 content:
5191 application/json:
5192 schema:
5193 $ref: '#/components/schemas/ServerStats'
5194
5195 /api/v1/server/logs/client:
5196 post:
5197 tags:
5198 - Logs
5199 summary: Send client log
5200 operationId: sendClientLog
5201 requestBody:
5202 content:
5203 application/json:
5204 schema:
5205 $ref: '#/components/schemas/SendClientLog'
5206 responses:
5207 '204':
5208 description: successful operation
5209
5210 /api/v1/server/logs:
5211 get:
5212 tags:
5213 - Logs
5214 summary: Get instance logs
5215 operationId: getInstanceLogs
5216 security:
5217 - OAuth2:
5218 - admin
5219 responses:
5220 '200':
5221 description: successful operation
5222 content:
5223 application/json:
5224 schema:
5225 type: array
5226 items:
5227 type: string
5228
5229 /api/v1/server/audit-logs:
5230 get:
5231 tags:
5232 - Logs
5233 summary: Get instance audit logs
5234 operationId: getInstanceAuditLogs
5235 security:
5236 - OAuth2:
5237 - admin
5238 responses:
5239 '200':
5240 description: successful operation
5241 content:
5242 application/json:
5243 schema:
5244 type: array
5245 items:
5246 type: string
5247
5248 /api/v1/plugins:
5249 get:
5250 tags:
5251 - Plugins
5252 summary: List plugins
5253 operationId: getPlugins
5254 security:
5255 - OAuth2:
5256 - admin
5257 parameters:
5258 - name: pluginType
5259 in: query
5260 schema:
5261 type: integer
5262 - name: uninstalled
5263 in: query
5264 schema:
5265 type: boolean
5266 - $ref: '#/components/parameters/start'
5267 - $ref: '#/components/parameters/count'
5268 - $ref: '#/components/parameters/sort'
5269 responses:
5270 '200':
5271 description: successful operation
5272 content:
5273 application/json:
5274 schema:
5275 $ref: '#/components/schemas/PluginResponse'
5276
5277 /api/v1/plugins/available:
5278 get:
5279 tags:
5280 - Plugins
5281 summary: List available plugins
5282 operationId: getAvailablePlugins
5283 security:
5284 - OAuth2:
5285 - admin
5286 parameters:
5287 - name: search
5288 in: query
5289 schema:
5290 type: string
5291 - name: pluginType
5292 in: query
5293 schema:
5294 type: integer
5295 - name: currentPeerTubeEngine
5296 in: query
5297 schema:
5298 type: string
5299 - $ref: '#/components/parameters/start'
5300 - $ref: '#/components/parameters/count'
5301 - $ref: '#/components/parameters/sort'
5302 responses:
5303 '200':
5304 description: successful operation
5305 content:
5306 application/json:
5307 schema:
5308 $ref: '#/components/schemas/PluginResponse'
5309 '503':
5310 description: plugin index unavailable
5311
5312 /api/v1/plugins/install:
5313 post:
5314 tags:
5315 - Plugins
5316 summary: Install a plugin
5317 operationId: addPlugin
5318 security:
5319 - OAuth2:
5320 - admin
5321 requestBody:
5322 content:
5323 application/json:
5324 schema:
5325 oneOf:
5326 - type: object
5327 properties:
5328 npmName:
5329 type: string
5330 example: peertube-plugin-auth-ldap
5331 required:
5332 - npmName
5333 additionalProperties: false
5334 - type: object
5335 properties:
5336 path:
5337 type: string
5338 required:
5339 - path
5340 additionalProperties: false
5341 responses:
5342 '204':
5343 description: successful operation
5344 '400':
5345 description: should have either `npmName` or `path` set
5346
5347 /api/v1/plugins/update:
5348 post:
5349 tags:
5350 - Plugins
5351 summary: Update a plugin
5352 operationId: updatePlugin
5353 security:
5354 - OAuth2:
5355 - admin
5356 requestBody:
5357 content:
5358 application/json:
5359 schema:
5360 oneOf:
5361 - type: object
5362 properties:
5363 npmName:
5364 type: string
5365 example: peertube-plugin-auth-ldap
5366 required:
5367 - npmName
5368 additionalProperties: false
5369 - type: object
5370 properties:
5371 path:
5372 type: string
5373 required:
5374 - path
5375 additionalProperties: false
5376 responses:
5377 '204':
5378 description: successful operation
5379 '400':
5380 description: should have either `npmName` or `path` set
5381 '404':
5382 description: existing plugin not found
5383
5384 /api/v1/plugins/uninstall:
5385 post:
5386 tags:
5387 - Plugins
5388 summary: Uninstall a plugin
5389 operationId: uninstallPlugin
5390 security:
5391 - OAuth2:
5392 - admin
5393 requestBody:
5394 content:
5395 application/json:
5396 schema:
5397 type: object
5398 properties:
5399 npmName:
5400 type: string
5401 description: name of the plugin/theme in its package.json
5402 example: peertube-plugin-auth-ldap
5403 required:
5404 - npmName
5405 responses:
5406 '204':
5407 description: successful operation
5408 '404':
5409 description: existing plugin not found
5410
5411 /api/v1/plugins/{npmName}:
5412 get:
5413 tags:
5414 - Plugins
5415 summary: Get a plugin
5416 operationId: getPlugin
5417 security:
5418 - OAuth2:
5419 - admin
5420 parameters:
5421 - $ref: '#/components/parameters/npmName'
5422 responses:
5423 '200':
5424 description: successful operation
5425 content:
5426 application/json:
5427 schema:
5428 $ref: '#/components/schemas/Plugin'
5429 '404':
5430 description: plugin not found
5431
5432 /api/v1/plugins/{npmName}/settings:
5433 put:
5434 tags:
5435 - Plugins
5436 summary: Set a plugin's settings
5437 security:
5438 - OAuth2:
5439 - admin
5440 parameters:
5441 - $ref: '#/components/parameters/npmName'
5442 requestBody:
5443 content:
5444 application/json:
5445 schema:
5446 type: object
5447 properties:
5448 settings:
5449 type: object
5450 additionalProperties: true
5451 responses:
5452 '204':
5453 description: successful operation
5454 '404':
5455 description: plugin not found
5456
5457 /api/v1/plugins/{npmName}/public-settings:
5458 get:
5459 tags:
5460 - Plugins
5461 summary: Get a plugin's public settings
5462 parameters:
5463 - $ref: '#/components/parameters/npmName'
5464 responses:
5465 '200':
5466 description: successful operation
5467 content:
5468 application/json:
5469 schema:
5470 type: object
5471 additionalProperties: true
5472 '404':
5473 description: plugin not found
5474
5475 /api/v1/plugins/{npmName}/registered-settings:
5476 get:
5477 tags:
5478 - Plugins
5479 summary: Get a plugin's registered settings
5480 security:
5481 - OAuth2:
5482 - admin
5483 parameters:
5484 - $ref: '#/components/parameters/npmName'
5485 responses:
5486 '200':
5487 description: successful operation
5488 content:
5489 application/json:
5490 schema:
5491 type: object
5492 additionalProperties: true
5493 '404':
5494 description: plugin not found
5495
5496 /api/v1/metrics/playback:
5497 post:
5498 summary: Create playback metrics
5499 description: These metrics are exposed by OpenTelemetry metrics exporter if enabled.
5500 tags:
5501 - Stats
5502 requestBody:
5503 content:
5504 application/json:
5505 schema:
5506 $ref: '#/components/schemas/PlaybackMetricCreate'
5507 responses:
5508 '204':
5509 description: successful operation
5510
5511 /api/v1/runners/registration-tokens/generate:
5512 post:
5513 summary: Generate registration token
5514 description: Generate a new runner registration token
5515 security:
5516 - OAuth2:
5517 - admin
5518 tags:
5519 - Runner Registration Token
5520 responses:
5521 '204':
5522 description: successful operation
5523
5524 /api/v1/runners/registration-tokens/{registrationTokenId}:
5525 delete:
5526 summary: Remove registration token
5527 description: Remove a registration token. Runners that used this token for their registration are automatically removed.
5528 security:
5529 - OAuth2:
5530 - admin
5531 tags:
5532 - Runner Registration Token
5533 parameters:
5534 - $ref: '#/components/parameters/registrationTokenId'
5535 responses:
5536 '204':
5537 description: successful operation
5538
5539 /api/v1/runners/registration-tokens:
5540 get:
5541 summary: List registration tokens
5542 security:
5543 - OAuth2:
5544 - admin
5545 tags:
5546 - Runner Registration Token
5547 parameters:
5548 - $ref: '#/components/parameters/start'
5549 - $ref: '#/components/parameters/count'
5550 - $ref: '#/components/parameters/registrationTokenSort'
5551 responses:
5552 '200':
5553 description: successful operation
5554 content:
5555 application/json:
5556 schema:
5557 type: object
5558 properties:
5559 total:
5560 type: integer
5561 example: 1
5562 data:
5563 type: array
5564 items:
5565 $ref: '#/components/schemas/RunnerRegistrationToken'
5566
5567 /api/v1/runners/register:
5568 post:
5569 summary: Register a new runner
5570 description: API used by PeerTube runners
5571 tags:
5572 - Runners
5573 requestBody:
5574 content:
5575 application/json:
5576 schema:
5577 type: object
5578 properties:
5579 registrationToken:
5580 type: string
5581 name:
5582 type: string
5583 description:
5584 type: string
5585 required:
5586 - registrationToken
5587 - name
5588 responses:
5589 '200':
5590 description: successful operation
5591 content:
5592 application/json:
5593 schema:
5594 type: object
5595 properties:
5596 id:
5597 type: integer
5598 description: Runner id
5599 runnerToken:
5600 type: string
5601
5602 /api/v1/runners/unregister:
5603 post:
5604 summary: Unregister a runner
5605 description: API used by PeerTube runners
5606 tags:
5607 - Runners
5608 requestBody:
5609 content:
5610 application/json:
5611 schema:
5612 type: object
5613 properties:
5614 runnerToken:
5615 type: string
5616 required:
5617 - runnerToken
5618 responses:
5619 '204':
5620 description: successful operation
5621
5622 /api/v1/runners/{runnerId}:
5623 delete:
5624 summary: Delete a runner
5625 security:
5626 - OAuth2:
5627 - admin
5628 tags:
5629 - Runners
5630 parameters:
5631 - $ref: '#/components/parameters/runnerId'
5632 requestBody:
5633 content:
5634 application/json:
5635 schema:
5636 type: object
5637 properties:
5638 runnerToken:
5639 type: string
5640 required:
5641 - runnerToken
5642 responses:
5643 '204':
5644 description: successful operation
5645
5646 /api/v1/runners:
5647 get:
5648 summary: List runners
5649 security:
5650 - OAuth2:
5651 - admin
5652 tags:
5653 - Runners
5654 parameters:
5655 - $ref: '#/components/parameters/start'
5656 - $ref: '#/components/parameters/count'
5657 - $ref: '#/components/parameters/runnerSort'
5658 responses:
5659 '200':
5660 description: successful operation
5661 content:
5662 application/json:
5663 schema:
5664 type: object
5665 properties:
5666 total:
5667 type: integer
5668 example: 1
5669 data:
5670 type: array
5671 items:
5672 $ref: '#/components/schemas/Runner'
5673
5674
5675 /api/v1/runners/jobs/request:
5676 post:
5677 summary: Request a new job
5678 description: API used by PeerTube runners
5679 tags:
5680 - Runner Jobs
5681 requestBody:
5682 content:
5683 application/json:
5684 schema:
5685 type: object
5686 properties:
5687 runnerToken:
5688 type: string
5689 required:
5690 - runnerToken
5691 responses:
5692 '200':
5693 description: successful operation
5694 content:
5695 application/json:
5696 schema:
5697 type: object
5698 properties:
5699 availableJobs:
5700 type: array
5701 items:
5702 type: object
5703 properties:
5704 uuid:
5705 $ref: '#/components/schemas/UUIDv4'
5706 type:
5707 $ref: '#/components/schemas/RunnerJobType'
5708 payload:
5709 $ref: '#/components/schemas/RunnerJobPayload'
5710
5711 /api/v1/runners/jobs/{jobUUID}/accept:
5712 post:
5713 summary: Accept job
5714 description: API used by PeerTube runners
5715 tags:
5716 - Runner Jobs
5717 parameters:
5718 - $ref: '#/components/parameters/jobUUID'
5719 requestBody:
5720 content:
5721 application/json:
5722 schema:
5723 type: object
5724 properties:
5725 runnerToken:
5726 type: string
5727 required:
5728 - runnerToken
5729 responses:
5730 '200':
5731 description: successful operation
5732 content:
5733 application/json:
5734 schema:
5735 type: object
5736 properties:
5737 job:
5738 allOf:
5739 - $ref: '#/components/schemas/RunnerJob'
5740 - type: object
5741 properties:
5742 jobToken:
5743 type: string
5744
5745 /api/v1/runners/jobs/{jobUUID}/abort:
5746 post:
5747 summary: Abort job
5748 description: API used by PeerTube runners
5749 tags:
5750 - Runner Jobs
5751 parameters:
5752 - $ref: '#/components/parameters/jobUUID'
5753 requestBody:
5754 content:
5755 application/json:
5756 schema:
5757 type: object
5758 properties:
5759 runnerToken:
5760 type: string
5761 jobToken:
5762 type: string
5763 reason:
5764 type: string
5765 description: Why the runner aborts this job
5766 required:
5767 - runnerToken
5768 - jobToken
5769 - reason
5770 responses:
5771 '204':
5772 description: successful operation
5773
5774 /api/v1/runners/jobs/{jobUUID}/update:
5775 post:
5776 summary: Update job
5777 description: API used by PeerTube runners
5778 tags:
5779 - Runner Jobs
5780 parameters:
5781 - $ref: '#/components/parameters/jobUUID'
5782 requestBody:
5783 content:
5784 application/json:
5785 schema:
5786 type: object
5787 properties:
5788 runnerToken:
5789 type: string
5790 jobToken:
5791 type: string
5792 progress:
5793 type: integer
5794 description: Update job progression percentage (optional)
5795 payload:
5796 anyOf:
5797 - type: object
5798 description: Provide live transcoding chunks update
5799 properties:
5800 type:
5801 type: string
5802 enum:
5803 - 'add-chunk'
5804 - 'remove-chunk'
5805 masterPlaylistFile:
5806 type: string
5807 format: binary
5808 resolutionPlaylistFile:
5809 type: string
5810 format: binary
5811 resolutionPlaylistFilename:
5812 type: string
5813 videoChunkFile:
5814 type: string
5815 format: binary
5816 videoChunkFilename:
5817 type: string
5818 required:
5819 - runnerToken
5820 - jobToken
5821 responses:
5822 '204':
5823 description: successful operation
5824
5825 /api/v1/runners/jobs/{jobUUID}/error:
5826 post:
5827 summary: Post job error
5828 description: API used by PeerTube runners
5829 tags:
5830 - Runner Jobs
5831 parameters:
5832 - $ref: '#/components/parameters/jobUUID'
5833 requestBody:
5834 content:
5835 application/json:
5836 schema:
5837 type: object
5838 properties:
5839 runnerToken:
5840 type: string
5841 jobToken:
5842 type: string
5843 message:
5844 type: string
5845 description: Why the runner failed to process this job
5846 required:
5847 - runnerToken
5848 - jobToken
5849 - message
5850 responses:
5851 '204':
5852 description: successful operation
5853
5854 /api/v1/runners/jobs/{jobUUID}/success:
5855 post:
5856 summary: Post job success
5857 description: API used by PeerTube runners
5858 tags:
5859 - Runner Jobs
5860 parameters:
5861 - $ref: '#/components/parameters/jobUUID'
5862 requestBody:
5863 content:
5864 application/json:
5865 schema:
5866 type: object
5867 properties:
5868 runnerToken:
5869 type: string
5870 jobToken:
5871 type: string
5872 payload:
5873 anyOf:
5874 - type: object
5875 title: VOD web video transcoding
5876 properties:
5877 videoFile:
5878 type: string
5879 format: binary
5880 - type: object
5881 title: VOD HLS transcoding
5882 properties:
5883 videoFile:
5884 type: string
5885 format: binary
5886 resolutionPlaylistFile:
5887 type: string
5888 format: binary
5889 - type: object
5890 title: VOD audio merge transcoding
5891 properties:
5892 videoFile:
5893 type: string
5894 format: binary
5895 - type: object
5896 title: Live RTMP to HLS transcoding
5897 required:
5898 - runnerToken
5899 - jobToken
5900 - payload
5901 responses:
5902 '204':
5903 description: successful operation
5904
5905 /api/v1/runners/jobs/{jobUUID}/cancel:
5906 get:
5907 summary: Cancel a job
5908 security:
5909 - OAuth2:
5910 - admin
5911 tags:
5912 - Runner Jobs
5913 parameters:
5914 - $ref: '#/components/parameters/jobUUID'
5915 responses:
5916 '204':
5917 description: successful operation
5918
5919 /api/v1/runners/jobs:
5920 get:
5921 summary: List jobs
5922 security:
5923 - OAuth2:
5924 - admin
5925 tags:
5926 - Runner Jobs
5927 parameters:
5928 - $ref: '#/components/parameters/start'
5929 - $ref: '#/components/parameters/count'
5930 - $ref: '#/components/parameters/runnerJobSort'
5931 - $ref: '#/components/parameters/search'
5932 responses:
5933 '200':
5934 description: successful operation
5935 content:
5936 application/json:
5937 schema:
5938 type: object
5939 properties:
5940 total:
5941 type: integer
5942 example: 1
5943 data:
5944 type: array
5945 items:
5946 $ref: '#/components/schemas/RunnerJobAdmin'
5947
5948servers:
5949 - url: 'https://peertube2.cpy.re'
5950 description: Live Test Server (live data - latest nightly version)
5951 - url: 'https://peertube3.cpy.re'
5952 description: Live Test Server (live data - latest RC version)
5953 - url: 'https://peertube.cpy.re'
5954 description: Live Test Server (live data - stable version)
5955components:
5956 parameters:
5957 start:
5958 name: start
5959 in: query
5960 required: false
5961 description: Offset used to paginate results
5962 schema:
5963 type: integer
5964 minimum: 0
5965 count:
5966 name: count
5967 in: query
5968 required: false
5969 description: "Number of items to return"
5970 schema:
5971 type: integer
5972 default: 15
5973 maximum: 100
5974 minimum: 1
5975 sort:
5976 name: sort
5977 in: query
5978 required: false
5979 description: Sort column
5980 schema:
5981 type: string
5982 example: -createdAt
5983 search:
5984 name: search
5985 in: query
5986 required: false
5987 description: Plain text search, applied to various parts of the model depending on endpoint
5988 schema:
5989 type: string
5990 searchTarget:
5991 name: searchTarget
5992 in: query
5993 required: false
5994 description: >
5995 If the administrator enabled search index support, you can override the default search target.
5996
5997
5998 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
5999 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
6000 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
6001 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
6002 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
6003 * 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
6004 the data from the origin instance API
6005 schema:
6006 type: string
6007 enum:
6008 - 'local'
6009 - 'search-index'
6010 videosSort:
6011 name: sort
6012 in: query
6013 required: false
6014 schema:
6015 type: string
6016 enum:
6017 - name
6018 - -duration
6019 - -createdAt
6020 - -publishedAt
6021 - -views
6022 - -likes
6023 - -trending
6024 - -hot
6025 - -best
6026 description: >
6027 Sort videos by criteria (prefixing with `-` means `DESC` order):
6028 * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
6029 * `best` - Same than `hot`, but also takes into account user video history
6030 * `trending` - Sort videos by recent views ("recent" is defined by the admin)
6031 * `views` - Sort videos using their `views` counter
6032 * `publishedAt` - Sort by video publication date (when it became publicly available)
6033 videosSearchSort:
6034 name: sort
6035 in: query
6036 required: false
6037 description: >
6038 Sort videos by criteria (prefixing with `-` means `DESC` order):
6039 schema:
6040 type: string
6041 enum:
6042 - name
6043 - -duration
6044 - -createdAt
6045 - -publishedAt
6046 - -views
6047 - -likes
6048 - -match
6049 commentsSort:
6050 name: sort
6051 in: query
6052 required: false
6053 description: Sort comments by criteria
6054 schema:
6055 type: string
6056 enum:
6057 - -createdAt
6058 - -totalReplies
6059 blacklistsSort:
6060 name: sort
6061 in: query
6062 required: false
6063 description: Sort blocklists by criteria
6064 schema:
6065 type: string
6066 enum:
6067 - -id
6068 - name
6069 - -duration
6070 - -views
6071 - -likes
6072 - -dislikes
6073 - -uuid
6074 - -createdAt
6075 usersSearch:
6076 name: search
6077 in: query
6078 required: false
6079 description: Plain text search that will match with user usernames or emails
6080 schema:
6081 type: string
6082 usersBlocked:
6083 name: blocked
6084 in: query
6085 required: false
6086 description: Filter results down to (un)banned users
6087 schema:
6088 type: boolean
6089 usersSort:
6090 name: sort
6091 in: query
6092 required: false
6093 description: Sort users by criteria
6094 schema:
6095 type: string
6096 enum:
6097 - -id
6098 - -username
6099 - -createdAt
6100 abusesSort:
6101 name: sort
6102 in: query
6103 required: false
6104 description: Sort abuses by criteria
6105 schema:
6106 type: string
6107 enum:
6108 - -id
6109 - -createdAt
6110 - -state
6111 videoRedundanciesSort:
6112 name: sort
6113 in: query
6114 required: false
6115 description: Sort abuses by criteria
6116 schema:
6117 type: string
6118 enum:
6119 - name
6120 followersSort:
6121 name: sort
6122 in: query
6123 required: false
6124 description: Sort followers by criteria
6125 schema:
6126 type: string
6127 enum:
6128 - createdAt
6129 registrationTokenSort:
6130 name: sort
6131 in: query
6132 required: false
6133 description: Sort registration tokens by criteria
6134 schema:
6135 type: string
6136 enum:
6137 - createdAt
6138 runnerSort:
6139 name: sort
6140 in: query
6141 required: false
6142 description: Sort runners by criteria
6143 schema:
6144 type: string
6145 enum:
6146 - createdAt
6147 runnerJobSort:
6148 name: sort
6149 in: query
6150 required: false
6151 description: Sort runner jobs by criteria
6152 schema:
6153 type: string
6154 enum:
6155 - updatedAt
6156 - createdAt
6157 - priority
6158 - state
6159 - progress
6160
6161 name:
6162 name: name
6163 in: path
6164 required: true
6165 description: The username or handle of the account
6166 schema:
6167 type: string
6168 example: chocobozzz | chocobozzz@example.org
6169 id:
6170 name: id
6171 in: path
6172 required: true
6173 description: Entity id
6174 schema:
6175 $ref: '#/components/schemas/id'
6176 registrationId:
6177 name: registrationId
6178 in: path
6179 required: true
6180 description: Registration ID
6181 schema:
6182 $ref: '#/components/schemas/id'
6183 idOrUUID:
6184 name: id
6185 in: path
6186 required: true
6187 description: The object id, uuid or short uuid
6188 schema:
6189 oneOf:
6190 - $ref: '#/components/schemas/id'
6191 - $ref: '#/components/schemas/UUIDv4'
6192 - $ref: '#/components/schemas/shortUUID'
6193 playlistId:
6194 name: playlistId
6195 in: path
6196 required: true
6197 description: Playlist id
6198 schema:
6199 $ref: '#/components/schemas/VideoPlaylist/properties/id'
6200 playlistElementId:
6201 name: playlistElementId
6202 in: path
6203 required: true
6204 description: Playlist element id
6205 schema:
6206 $ref: '#/components/schemas/id'
6207 abuseId:
6208 name: abuseId
6209 in: path
6210 required: true
6211 description: Abuse id
6212 schema:
6213 $ref: '#/components/schemas/Abuse/properties/id'
6214 abuseMessageId:
6215 name: abuseMessageId
6216 in: path
6217 required: true
6218 description: Abuse message id
6219 schema:
6220 $ref: '#/components/schemas/AbuseMessage/properties/id'
6221 captionLanguage:
6222 name: captionLanguage
6223 in: path
6224 required: true
6225 description: The caption language
6226 schema:
6227 $ref: '#/components/schemas/VideoLanguageSet'
6228 channelHandle:
6229 name: channelHandle
6230 in: path
6231 required: true
6232 description: The video channel handle
6233 schema:
6234 type: string
6235 example: my_username | my_username@example.com
6236 channelSyncId:
6237 name: channelSyncId
6238 in: path
6239 required: true
6240 description: Channel Sync id
6241 schema:
6242 $ref: '#/components/schemas/Abuse/properties/id'
6243 subscriptionHandle:
6244 name: subscriptionHandle
6245 in: path
6246 required: true
6247 description: The subscription handle
6248 schema:
6249 type: string
6250 example: my_username | my_username@example.com
6251 threadId:
6252 name: threadId
6253 in: path
6254 required: true
6255 description: The thread id (root comment id)
6256 schema:
6257 type: integer
6258 commentId:
6259 name: commentId
6260 in: path
6261 required: true
6262 description: The comment id
6263 schema:
6264 $ref: '#/components/schemas/VideoComment/properties/id'
6265 isLive:
6266 name: isLive
6267 in: query
6268 required: false
6269 description: whether or not the video is a live
6270 schema:
6271 type: boolean
6272 categoryOneOf:
6273 name: categoryOneOf
6274 in: query
6275 required: false
6276 description: category id of the video (see [/videos/categories](#operation/getCategories))
6277 schema:
6278 oneOf:
6279 - $ref: '#/components/schemas/VideoCategorySet'
6280 - type: array
6281 items:
6282 $ref: '#/components/schemas/VideoCategorySet'
6283 style: form
6284 explode: false
6285 tagsOneOf:
6286 name: tagsOneOf
6287 in: query
6288 required: false
6289 description: tag(s) of the video
6290 schema:
6291 oneOf:
6292 - type: string
6293 - type: array
6294 maxItems: 5
6295 items:
6296 type: string
6297 style: form
6298 explode: false
6299 tagsAllOf:
6300 name: tagsAllOf
6301 in: query
6302 required: false
6303 description: tag(s) of the video, where all should be present in the video
6304 schema:
6305 oneOf:
6306 - type: string
6307 - type: array
6308 items:
6309 type: string
6310 style: form
6311 explode: false
6312 languageOneOf:
6313 name: languageOneOf
6314 in: query
6315 required: false
6316 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
6317 schema:
6318 oneOf:
6319 - $ref: '#/components/schemas/VideoLanguageSet'
6320 - type: array
6321 items:
6322 $ref: '#/components/schemas/VideoLanguageSet'
6323 style: form
6324 explode: false
6325 licenceOneOf:
6326 name: licenceOneOf
6327 in: query
6328 required: false
6329 description: licence id of the video (see [/videos/licences](#operation/getLicences))
6330 schema:
6331 oneOf:
6332 - $ref: '#/components/schemas/VideoLicenceSet'
6333 - type: array
6334 items:
6335 $ref: '#/components/schemas/VideoLicenceSet'
6336 style: form
6337 explode: false
6338 skipCount:
6339 name: skipCount
6340 in: query
6341 required: false
6342 description: if you don't need the `total` in the response
6343 schema:
6344 type: string
6345 enum:
6346 - 'true'
6347 - 'false'
6348 default: 'false'
6349 nsfw:
6350 name: nsfw
6351 in: query
6352 required: false
6353 description: whether to include nsfw videos, if any
6354 schema:
6355 type: string
6356 enum:
6357 - 'true'
6358 - 'false'
6359 isLocal:
6360 name: isLocal
6361 in: query
6362 required: false
6363 schema:
6364 type: boolean
6365 description: '**PeerTube >= 4.0** Display only local or remote videos'
6366 hasHLSFiles:
6367 name: hasHLSFiles
6368 in: query
6369 required: false
6370 schema:
6371 type: boolean
6372 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
6373 hasWebtorrentFiles:
6374 name: hasWebtorrentFiles
6375 in: query
6376 required: false
6377 schema:
6378 type: boolean
6379 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
6380 privacyOneOf:
6381 name: privacyOneOf
6382 in: query
6383 required: false
6384 schema:
6385 $ref: '#/components/schemas/VideoPrivacySet'
6386 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
6387 excludeAlreadyWatched:
6388 name: excludeAlreadyWatched
6389 in: query
6390 description: Whether or not to exclude videos that are in the user's video history
6391 schema:
6392 type: boolean
6393 uuids:
6394 name: uuids
6395 in: query
6396 required: false
6397 schema:
6398 items:
6399 type: string
6400 description: 'Find videos with specific UUIDs'
6401 include:
6402 name: include
6403 in: query
6404 required: false
6405 schema:
6406 type: integer
6407 enum:
6408 - 0
6409 - 1
6410 - 2
6411 - 4
6412 - 8
6413 description: >
6414 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
6415
6416 - `0` NONE
6417
6418 - `1` NOT_PUBLISHED_STATE
6419
6420 - `2` BLACKLISTED
6421
6422 - `4` BLOCKED_OWNER
6423
6424 - `8` FILES
6425 subscriptionsUris:
6426 name: uris
6427 in: query
6428 required: true
6429 description: list of uris to check if each is part of the user subscriptions
6430 schema:
6431 type: array
6432 items:
6433 type: string
6434 format: uri
6435 npmName:
6436 name: npmName
6437 in: path
6438 required: true
6439 description: name of the plugin/theme on npmjs.com or in its package.json
6440 schema:
6441 type: string
6442 example: peertube-plugin-auth-ldap
6443 jobType:
6444 name: jobType
6445 in: query
6446 required: false
6447 description: job type
6448 schema:
6449 type: string
6450 enum:
6451 - activitypub-follow
6452 - activitypub-http-broadcast
6453 - activitypub-http-fetcher
6454 - activitypub-http-unicast
6455 - email
6456 - video-transcoding
6457 - video-file-import
6458 - video-import
6459 - videos-views-stats
6460 - activitypub-refresher
6461 - video-redundancy
6462 - video-live-ending
6463 - video-channel-import
6464 followState:
6465 name: state
6466 in: query
6467 schema:
6468 type: string
6469 enum:
6470 - pending
6471 - accepted
6472 actorType:
6473 name: actorType
6474 in: query
6475 schema:
6476 type: string
6477 enum:
6478 - Person
6479 - Application
6480 - Group
6481 - Service
6482 - Organization
6483 staticFilename:
6484 name: filename
6485 in: path
6486 required: true
6487 description: Filename
6488 schema:
6489 type: string
6490 videoFileToken:
6491 name: videoFileToken
6492 in: query
6493 required: false
6494 description: Video file token [generated](#operation/requestVideoToken) by PeerTube so you don't need to provide an OAuth token in the request header.
6495 schema:
6496 type: string
6497 reinjectVideoFileToken:
6498 name: reinjectVideoFileToken
6499 in: query
6500 required: false
6501 description: Ask the server to reinject videoFileToken in URLs in m3u8 playlist
6502 schema:
6503 type: boolean
6504 videoPlaylistType:
6505 name: playlistType
6506 in: query
6507 required: false
6508 schema:
6509 $ref: '#/components/schemas/VideoPlaylistTypeSet'
6510 registrationTokenId:
6511 name: registrationTokenId
6512 in: path
6513 required: true
6514 schema:
6515 type: integer
6516 runnerId:
6517 name: runnerId
6518 in: path
6519 required: true
6520 schema:
6521 type: integer
6522 jobUUID:
6523 name: jobUUID
6524 in: path
6525 required: true
6526 schema:
6527 $ref: '#/components/schemas/UUIDv4'
6528
6529 securitySchemes:
6530 OAuth2:
6531 description: |
6532 Authenticating via OAuth requires the following steps:
6533 - Have an activated account
6534 - [Generate] an access token for that account at `/api/v1/users/token`.
6535 - Make requests with the *Authorization: Bearer <token\>* header
6536 - Profit, depending on the role assigned to the account
6537
6538 Note that the __access token is valid for 1 day__ and is given
6539 along with a __refresh token valid for 2 weeks__.
6540
6541 [Generate]: https://docs.joinpeertube.org/api/rest-getting-started
6542 type: oauth2
6543 flows:
6544 password:
6545 tokenUrl: /api/v1/users/token
6546 scopes:
6547 admin: Admin scope
6548 moderator: Moderator scope
6549 user: User scope
6550 schemas:
6551 # Reusable core properties
6552 id:
6553 type: integer
6554 minimum: 1
6555 example: 42
6556 UUIDv4:
6557 type: string
6558 format: uuid
6559 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
6560 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
6561 minLength: 36
6562 maxLength: 36
6563 shortUUID:
6564 type: string
6565 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
6566 example: 2y84q2MQUMWPbiEcxNXMgC
6567 username:
6568 type: string
6569 description: immutable name of the user, used to find or mention its actor
6570 example: chocobozzz
6571 pattern: '/^[a-z0-9._]+$/'
6572 minLength: 1
6573 maxLength: 50
6574 usernameChannel:
6575 type: string
6576 description: immutable name of the channel, used to interact with its actor
6577 example: framasoft_videos
6578 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
6579 minLength: 1
6580 maxLength: 50
6581 password:
6582 type: string
6583 format: password
6584 minLength: 6
6585 maxLength: 255
6586
6587 VideoCategorySet:
6588 type: integer
6589 description: category id of the video (see [/videos/categories](#operation/getCategories))
6590 example: 15
6591 VideoConstantNumber-Category:
6592 properties:
6593 id:
6594 $ref: '#/components/schemas/VideoCategorySet'
6595 label:
6596 type: string
6597 example: Science & Technology
6598
6599 VideoLicenceSet:
6600 type: integer
6601 description: licence id of the video (see [/videos/licences](#operation/getLicences))
6602 example: 2
6603 VideoConstantNumber-Licence:
6604 properties:
6605 id:
6606 $ref: '#/components/schemas/VideoLicenceSet'
6607 label:
6608 type: string
6609 example: Attribution - Share Alike
6610
6611 VideoLanguageSet:
6612 type: string
6613 description: language id of the video (see [/videos/languages](#operation/getLanguages))
6614 example: en
6615 VideoConstantString-Language:
6616 properties:
6617 id:
6618 $ref: '#/components/schemas/VideoLanguageSet'
6619 label:
6620 type: string
6621 example: English
6622
6623 VideoPlaylistPrivacySet:
6624 type: integer
6625 enum:
6626 - 1
6627 - 2
6628 - 3
6629 description: Video playlist privacy policy (see [/video-playlists/privacies](#operation/getPlaylistPrivacyPolicies))
6630 VideoPlaylistPrivacyConstant:
6631 properties:
6632 id:
6633 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
6634 label:
6635 type: string
6636
6637 VideoPlaylistTypeSet:
6638 type: integer
6639 enum:
6640 - 1
6641 - 2
6642 description: The video playlist type (Regular = `1`, Watch Later = `2`)
6643 VideoPlaylistTypeConstant:
6644 properties:
6645 id:
6646 $ref: '#/components/schemas/VideoPlaylistTypeSet'
6647 label:
6648 type: string
6649
6650 VideoPrivacySet:
6651 type: integer
6652 enum:
6653 - 1
6654 - 2
6655 - 3
6656 - 4
6657 description: privacy id of the video (see [/videos/privacies](#operation/getVideoPrivacyPolicies))
6658 VideoPrivacyConstant:
6659 properties:
6660 id:
6661 $ref: '#/components/schemas/VideoPrivacySet'
6662 label:
6663 type: string
6664
6665 BlockStatus:
6666 properties:
6667 accounts:
6668 type: object
6669 additionalProperties:
6670 x-additionalPropertiesName: account
6671 type: object
6672 properties:
6673 blockedByServer:
6674 type: boolean
6675 blockedByUser:
6676 type: boolean
6677 hosts:
6678 type: object
6679 additionalProperties:
6680 x-additionalPropertiesName: host
6681 type: object
6682 properties:
6683 blockedByServer:
6684 type: boolean
6685 blockedByUser:
6686 type: boolean
6687
6688 NSFWPolicy:
6689 type: string
6690 enum:
6691 - display
6692 - blur
6693 - do_not_list
6694
6695 UserRole:
6696 type: integer
6697 enum:
6698 - 0
6699 - 1
6700 - 2
6701 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
6702 example: 2
6703 UserAdminFlags:
6704 type: integer
6705 enum:
6706 - 0
6707 - 1
6708 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
6709 example: 1
6710
6711 LiveVideoLatencyMode:
6712 type: integer
6713 enum:
6714 - 1
6715 - 2
6716 - 3
6717 description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
6718
6719 LiveVideoReplaySettings:
6720 type: object
6721 properties:
6722 privacy:
6723 # description: Video playlist privacy policy (see [../video-playlists/privacies])
6724 $ref: '#/components/schemas/VideoPrivacySet'
6725
6726
6727 VideoStateConstant:
6728 properties:
6729 id:
6730 type: integer
6731 enum:
6732 - 1
6733 - 2
6734 - 3
6735 - 4
6736 - 5
6737 - 6
6738 - 7
6739 - 8
6740 - 9
6741 description: |
6742 The video state:
6743 - `1`: Published
6744 - `2`: To transcode
6745 - `3`: To import
6746 - `4`: Waiting for live stream
6747 - `5`: Live ended
6748 - `6`: To move to an external storage (object storage...)
6749 - `7`: Transcoding failed
6750 - `8`: Moving to an external storage failed
6751 - `9`: To edit using studio edition feature
6752 label:
6753 type: string
6754
6755 AbuseStateSet:
6756 type: integer
6757 enum:
6758 - 1
6759 - 2
6760 - 3
6761 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
6762 AbuseStateConstant:
6763 properties:
6764 id:
6765 $ref: '#/components/schemas/AbuseStateSet'
6766 label:
6767 type: string
6768 AbusePredefinedReasons:
6769 type: array
6770 items:
6771 type: string
6772 enum:
6773 - violentOrAbusive
6774 - hatefulOrAbusive
6775 - spamOrMisleading
6776 - privacy
6777 - rights
6778 - serverRules
6779 - thumbnails
6780 - captions
6781 example: [spamOrMisleading]
6782
6783 VideoResolutionSet:
6784 type: integer
6785 description: |
6786 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
6787
6788 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
6789 example: 240
6790 VideoResolutionConstant:
6791 description: resolutions and their labels for the video
6792 properties:
6793 id:
6794 $ref: '#/components/schemas/VideoResolutionSet'
6795 label:
6796 type: string
6797 example: 240p
6798 VideoScheduledUpdate:
6799 properties:
6800 privacy:
6801 $ref: '#/components/schemas/VideoPrivacySet'
6802 updateAt:
6803 type: string
6804 format: date
6805 description: When to update the video
6806 required:
6807 - updateAt
6808 AccountSummary:
6809 properties:
6810 id:
6811 type: integer
6812 name:
6813 type: string
6814 displayName:
6815 type: string
6816 url:
6817 type: string
6818 format: url
6819 host:
6820 type: string
6821 format: hostname
6822 avatars:
6823 type: array
6824 items:
6825 $ref: '#/components/schemas/ActorImage'
6826 VideoChannelSummary:
6827 properties:
6828 id:
6829 $ref: '#/components/schemas/id'
6830 name:
6831 type: string
6832 displayName:
6833 type: string
6834 url:
6835 type: string
6836 format: url
6837 host:
6838 type: string
6839 format: hostname
6840 avatars:
6841 type: array
6842 items:
6843 $ref: '#/components/schemas/ActorImage'
6844 PlaylistElement:
6845 properties:
6846 position:
6847 type: integer
6848 startTimestamp:
6849 type: integer
6850 format: seconds
6851 stopTimestamp:
6852 type: integer
6853 format: seconds
6854 video:
6855 nullable: true
6856 allOf:
6857 - $ref: '#/components/schemas/Video'
6858 VideoFile:
6859 readOnly: true
6860 properties:
6861 id:
6862 $ref: '#/components/schemas/id'
6863 magnetUri:
6864 type: string
6865 format: uri
6866 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
6867 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6868 resolution:
6869 $ref: '#/components/schemas/VideoResolutionConstant'
6870 size:
6871 type: integer
6872 description: Video file size in bytes
6873 torrentUrl:
6874 type: string
6875 description: Direct URL of the torrent file
6876 format: url
6877 torrentDownloadUrl:
6878 type: string
6879 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
6880 format: url
6881 fileUrl:
6882 type: string
6883 description: Direct URL of the video
6884 format: url
6885 fileDownloadUrl:
6886 type: string
6887 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
6888 format: url
6889 fps:
6890 type: number
6891 description: Frames per second of the video file
6892 metadataUrl:
6893 type: string
6894 format: url
6895 description: URL dereferencing the output of ffprobe on the file
6896 VideoStreamingPlaylists:
6897 allOf:
6898 - type: object
6899 properties:
6900 id:
6901 $ref: '#/components/schemas/id'
6902 type:
6903 type: integer
6904 enum:
6905 - 1
6906 description: |
6907 Playlist type:
6908 - `1`: HLS
6909 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
6910 VideoStreamingPlaylists-HLS:
6911 properties:
6912 playlistUrl:
6913 type: string
6914 format: url
6915 segmentsSha256Url:
6916 type: string
6917 format: url
6918 files:
6919 type: array
6920 description: |
6921 Video files associated to this playlist.
6922
6923 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
6924 items:
6925 $ref: '#/components/schemas/VideoFile'
6926 redundancies:
6927 type: array
6928 items:
6929 type: object
6930 properties:
6931 baseUrl:
6932 type: string
6933 format: url
6934 VideoInfo:
6935 properties:
6936 id:
6937 $ref: '#/components/schemas/Video/properties/id'
6938 uuid:
6939 $ref: '#/components/schemas/Video/properties/uuid'
6940 name:
6941 $ref: '#/components/schemas/Video/properties/name'
6942 Video:
6943 properties:
6944 id:
6945 description: object id for the video
6946 allOf:
6947 - $ref: '#/components/schemas/id'
6948 uuid:
6949 description: universal identifier for the video, that can be used across instances
6950 allOf:
6951 - $ref: '#/components/schemas/UUIDv4'
6952 shortUUID:
6953 allOf:
6954 - $ref: '#/components/schemas/shortUUID'
6955 isLive:
6956 type: boolean
6957 createdAt:
6958 type: string
6959 format: date-time
6960 example: 2017-10-01T10:52:46.396Z
6961 description: time at which the video object was first drafted
6962 publishedAt:
6963 type: string
6964 format: date-time
6965 example: 2018-10-01T10:52:46.396Z
6966 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
6967 updatedAt:
6968 type: string
6969 format: date-time
6970 example: 2021-05-04T08:01:01.502Z
6971 description: last time the video's metadata was modified
6972 originallyPublishedAt:
6973 type: string
6974 format: date-time
6975 example: 2010-10-01T10:52:46.396Z
6976 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
6977 category:
6978 allOf:
6979 - $ref: '#/components/schemas/VideoConstantNumber-Category'
6980 description: category in which the video is classified
6981 licence:
6982 allOf:
6983 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
6984 description: licence under which the video is distributed
6985 language:
6986 allOf:
6987 - $ref: '#/components/schemas/VideoConstantString-Language'
6988 description: main language used in the video
6989 privacy:
6990 allOf:
6991 - $ref: '#/components/schemas/VideoPrivacyConstant'
6992 description: privacy policy used to distribute the video
6993 description:
6994 type: string
6995 example: |
6996 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
6997 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
6998 minLength: 3
6999 maxLength: 250
7000 description: |
7001 truncated description of the video, written in Markdown.
7002 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
7003 duration:
7004 type: integer
7005 example: 1419
7006 format: seconds
7007 description: duration of the video in seconds
7008 isLocal:
7009 type: boolean
7010 name:
7011 type: string
7012 description: title of the video
7013 example: What is PeerTube?
7014 minLength: 3
7015 maxLength: 120
7016 thumbnailPath:
7017 type: string
7018 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
7019 previewPath:
7020 type: string
7021 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
7022 embedPath:
7023 type: string
7024 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
7025 views:
7026 type: integer
7027 example: 1337
7028 likes:
7029 type: integer
7030 example: 42
7031 dislikes:
7032 type: integer
7033 example: 7
7034 nsfw:
7035 type: boolean
7036 waitTranscoding:
7037 type: boolean
7038 nullable: true
7039 state:
7040 allOf:
7041 - $ref: '#/components/schemas/VideoStateConstant'
7042 description: represents the internal state of the video processing within the PeerTube instance
7043 scheduledUpdate:
7044 nullable: true
7045 allOf:
7046 - $ref: '#/components/schemas/VideoScheduledUpdate'
7047 blacklisted:
7048 nullable: true
7049 type: boolean
7050 blacklistedReason:
7051 nullable: true
7052 type: string
7053 account:
7054 $ref: '#/components/schemas/AccountSummary'
7055 channel:
7056 $ref: '#/components/schemas/VideoChannelSummary'
7057 userHistory:
7058 nullable: true
7059 type: object
7060 properties:
7061 currentTime:
7062 type: integer
7063 VideoDetails:
7064 allOf:
7065 - $ref: '#/components/schemas/Video'
7066 - type: object
7067 properties:
7068 viewers:
7069 type: integer
7070 description: If the video is a live, you have the amount of current viewers
7071 descriptionPath:
7072 type: string
7073 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
7074 description: path at which to get the full description of maximum `10000` characters
7075 support:
7076 type: string
7077 description: A text tell the audience how to support the video creator
7078 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7079 minLength: 3
7080 maxLength: 1000
7081 channel:
7082 $ref: '#/components/schemas/VideoChannel'
7083 account:
7084 $ref: '#/components/schemas/Account'
7085 tags:
7086 example: [flowers, gardening]
7087 type: array
7088 minItems: 1
7089 maxItems: 5
7090 items:
7091 type: string
7092 minLength: 2
7093 maxLength: 30
7094 commentsEnabled:
7095 type: boolean
7096 downloadEnabled:
7097 type: boolean
7098 trackerUrls:
7099 type: array
7100 items:
7101 type: string
7102 format: url
7103 example:
7104 - https://peertube2.cpy.re/tracker/announce
7105 - wss://peertube2.cpy.re/tracker/socket
7106 files:
7107 type: array
7108 items:
7109 $ref: '#/components/schemas/VideoFile'
7110 description: |
7111 WebTorrent/raw video files. If WebTorrent is disabled on the server:
7112
7113 - field will be empty
7114 - video files will be found in `streamingPlaylists[].files` field
7115 streamingPlaylists:
7116 type: array
7117 items:
7118 $ref: '#/components/schemas/VideoStreamingPlaylists'
7119 description: |
7120 HLS playlists/manifest files. If HLS is disabled on the server:
7121
7122 - field will be empty
7123 - video files will be found in `files` field
7124 FileRedundancyInformation:
7125 properties:
7126 id:
7127 $ref: '#/components/schemas/id'
7128 fileUrl:
7129 type: string
7130 format: url
7131 strategy:
7132 type: string
7133 enum:
7134 - manual
7135 - most-views
7136 - trending
7137 - recently-added
7138 size:
7139 type: integer
7140 createdAt:
7141 type: string
7142 format: date-time
7143 updatedAt:
7144 type: string
7145 format: date-time
7146 expiresOn:
7147 type: string
7148 format: date-time
7149 VideoRedundancy:
7150 properties:
7151 id:
7152 $ref: '#/components/schemas/id'
7153 name:
7154 type: string
7155 url:
7156 type: string
7157 format: url
7158 uuid:
7159 $ref: '#/components/schemas/UUIDv4'
7160 redundancies:
7161 type: object
7162 properties:
7163 files:
7164 type: array
7165 items:
7166 $ref: '#/components/schemas/FileRedundancyInformation'
7167 streamingPlaylists:
7168 type: array
7169 items:
7170 $ref: '#/components/schemas/FileRedundancyInformation'
7171 VideoImportStateConstant:
7172 properties:
7173 id:
7174 type: integer
7175 enum:
7176 - 1
7177 - 2
7178 - 3
7179 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
7180 label:
7181 type: string
7182 example: Pending
7183 VideoCreateImport:
7184 allOf:
7185 - type: object
7186 additionalProperties: false
7187 oneOf:
7188 - properties:
7189 targetUrl:
7190 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
7191 required: [targetUrl]
7192 - properties:
7193 magnetUri:
7194 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7195 required: [magnetUri]
7196 - properties:
7197 torrentfile:
7198 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
7199 required: [torrentfile]
7200 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7201 required:
7202 - channelId
7203 - name
7204 VideoImport:
7205 properties:
7206 id:
7207 readOnly: true
7208 allOf:
7209 - $ref: '#/components/schemas/id'
7210 targetUrl:
7211 type: string
7212 format: url
7213 description: remote URL where to find the import's source video
7214 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
7215 magnetUri:
7216 type: string
7217 format: uri
7218 description: magnet URI allowing to resolve the import's source video
7219 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
7220 torrentfile:
7221 writeOnly: true
7222 type: string
7223 format: binary
7224 description: Torrent file containing only the video file
7225 torrentName:
7226 readOnly: true
7227 type: string
7228 state:
7229 readOnly: true
7230 allOf:
7231 - $ref: '#/components/schemas/VideoImportStateConstant'
7232 error:
7233 readOnly: true
7234 type: string
7235 createdAt:
7236 readOnly: true
7237 type: string
7238 format: date-time
7239 updatedAt:
7240 readOnly: true
7241 type: string
7242 format: date-time
7243 video:
7244 readOnly: true
7245 nullable: true
7246 allOf:
7247 - $ref: '#/components/schemas/Video'
7248 VideoImportsList:
7249 properties:
7250 total:
7251 type: integer
7252 example: 1
7253 data:
7254 type: array
7255 maxItems: 100
7256 items:
7257 $ref: '#/components/schemas/VideoImport'
7258 Abuse:
7259 properties:
7260 id:
7261 $ref: '#/components/schemas/id'
7262 reason:
7263 type: string
7264 example: The video is a spam
7265 minLength: 2
7266 maxLength: 3000
7267 predefinedReasons:
7268 $ref: '#/components/schemas/AbusePredefinedReasons'
7269 reporterAccount:
7270 $ref: '#/components/schemas/Account'
7271 state:
7272 $ref: '#/components/schemas/AbuseStateConstant'
7273 moderationComment:
7274 type: string
7275 example: Decided to ban the server since it spams us regularly
7276 minLength: 2
7277 maxLength: 3000
7278 video:
7279 $ref: '#/components/schemas/VideoInfo'
7280 createdAt:
7281 type: string
7282 format: date-time
7283 AbuseMessage:
7284 properties:
7285 id:
7286 $ref: '#/components/schemas/id'
7287 message:
7288 type: string
7289 minLength: 2
7290 maxLength: 3000
7291 byModerator:
7292 type: boolean
7293 createdAt:
7294 type: string
7295 format: date-time
7296 account:
7297 $ref: '#/components/schemas/AccountSummary'
7298 VideoBlacklist:
7299 properties:
7300 id:
7301 $ref: '#/components/schemas/id'
7302 videoId:
7303 $ref: '#/components/schemas/Video/properties/id'
7304 createdAt:
7305 type: string
7306 format: date-time
7307 updatedAt:
7308 type: string
7309 format: date-time
7310 name:
7311 type: string
7312 minLength: 3
7313 maxLength: 120
7314 uuid:
7315 $ref: '#/components/schemas/UUIDv4'
7316 description:
7317 type: string
7318 minLength: 3
7319 maxLength: 10000
7320 duration:
7321 type: integer
7322 views:
7323 type: integer
7324 likes:
7325 type: integer
7326 dislikes:
7327 type: integer
7328 nsfw:
7329 type: boolean
7330 VideoPlaylist:
7331 properties:
7332 id:
7333 $ref: '#/components/schemas/id'
7334 uuid:
7335 $ref: '#/components/schemas/UUIDv4'
7336 shortUUID:
7337 allOf:
7338 - $ref: '#/components/schemas/shortUUID'
7339 createdAt:
7340 type: string
7341 format: date-time
7342 updatedAt:
7343 type: string
7344 format: date-time
7345 description:
7346 type: string
7347 minLength: 3
7348 maxLength: 1000
7349 displayName:
7350 type: string
7351 minLength: 1
7352 maxLength: 120
7353 isLocal:
7354 type: boolean
7355 videoLength:
7356 type: integer
7357 minimum: 0
7358 thumbnailPath:
7359 type: string
7360 privacy:
7361 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
7362 type:
7363 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
7364 ownerAccount:
7365 $ref: '#/components/schemas/AccountSummary'
7366 videoChannel:
7367 $ref: '#/components/schemas/VideoChannelSummary'
7368 VideoComment:
7369 properties:
7370 id:
7371 $ref: '#/components/schemas/id'
7372 url:
7373 type: string
7374 format: url
7375 text:
7376 type: string
7377 format: html
7378 description: Text of the comment
7379 minLength: 1
7380 example: This video is wonderful!
7381 threadId:
7382 $ref: '#/components/schemas/id'
7383 inReplyToCommentId:
7384 nullable: true
7385 allOf:
7386 - $ref: '#/components/schemas/id'
7387 videoId:
7388 $ref: '#/components/schemas/Video/properties/id'
7389 createdAt:
7390 type: string
7391 format: date-time
7392 updatedAt:
7393 type: string
7394 format: date-time
7395 deletedAt:
7396 nullable: true
7397 type: string
7398 format: date-time
7399 default: null
7400 isDeleted:
7401 type: boolean
7402 default: false
7403 totalRepliesFromVideoAuthor:
7404 type: integer
7405 minimum: 0
7406 totalReplies:
7407 type: integer
7408 minimum: 0
7409 account:
7410 $ref: '#/components/schemas/Account'
7411 VideoCommentThreadTree:
7412 properties:
7413 comment:
7414 $ref: '#/components/schemas/VideoComment'
7415 children:
7416 type: array
7417 items:
7418 $ref: '#/components/schemas/VideoCommentThreadTree'
7419 VideoCaption:
7420 properties:
7421 language:
7422 $ref: '#/components/schemas/VideoConstantString-Language'
7423 captionPath:
7424 type: string
7425 VideoSource:
7426 properties:
7427 filename:
7428 type: string
7429 ActorImage:
7430 properties:
7431 path:
7432 type: string
7433 width:
7434 type: integer
7435 createdAt:
7436 type: string
7437 format: date-time
7438 updatedAt:
7439 type: string
7440 format: date-time
7441 ActorInfo:
7442 properties:
7443 id:
7444 $ref: '#/components/schemas/id'
7445 name:
7446 type: string
7447 displayName:
7448 type: string
7449 host:
7450 type: string
7451 format: hostname
7452 avatars:
7453 type: array
7454 items:
7455 $ref: '#/components/schemas/ActorImage'
7456 Actor:
7457 properties:
7458 id:
7459 $ref: '#/components/schemas/id'
7460 url:
7461 type: string
7462 format: url
7463 name:
7464 description: immutable name of the actor, used to find or mention it
7465 allOf:
7466 - $ref: '#/components/schemas/username'
7467 host:
7468 type: string
7469 format: hostname
7470 description: server on which the actor is resident
7471 hostRedundancyAllowed:
7472 type: boolean
7473 description: whether this actor's host allows redundancy of its videos
7474 followingCount:
7475 type: integer
7476 minimum: 0
7477 description: number of actors subscribed to by this actor, as seen by this instance
7478 followersCount:
7479 type: integer
7480 minimum: 0
7481 description: number of followers of this actor, as seen by this instance
7482 createdAt:
7483 type: string
7484 format: date-time
7485 updatedAt:
7486 type: string
7487 format: date-time
7488 Account:
7489 allOf:
7490 - $ref: '#/components/schemas/Actor'
7491 - properties:
7492 userId:
7493 description: object id for the user tied to this account
7494 allOf:
7495 - $ref: '#/components/schemas/User/properties/id'
7496 displayName:
7497 type: string
7498 description: editable name of the account, displayed in its representations
7499 minLength: 3
7500 maxLength: 120
7501 description:
7502 type: string
7503 description: text or bio displayed on the account's profile
7504 UserViewingVideo:
7505 required:
7506 - currentTime
7507 properties:
7508 currentTime:
7509 type: integer
7510 format: seconds
7511 description: timestamp within the video, in seconds
7512 example: 5
7513 viewEvent:
7514 type: string
7515 enum:
7516 - seek
7517 description: >
7518 Event since last viewing call:
7519 * `seek` - If the user seeked the video
7520
7521 VideoStatsOverall:
7522 properties:
7523 averageWatchTime:
7524 type: number
7525 totalWatchTime:
7526 type: number
7527 viewersPeak:
7528 type: number
7529 viewersPeakDate:
7530 type: string
7531 format: date-time
7532 countries:
7533 type: array
7534 items:
7535 type: object
7536 properties:
7537 isoCode:
7538 type: string
7539 viewers:
7540 type: number
7541
7542 VideoStatsRetention:
7543 properties:
7544 data:
7545 type: array
7546 items:
7547 type: object
7548 properties:
7549 second:
7550 type: number
7551 retentionPercent:
7552 type: number
7553
7554 VideoStatsTimeserie:
7555 properties:
7556 data:
7557 type: array
7558 items:
7559 type: object
7560 properties:
7561 date:
7562 type: string
7563 value:
7564 type: number
7565
7566 ServerConfig:
7567 properties:
7568 instance:
7569 type: object
7570 properties:
7571 name:
7572 type: string
7573 shortDescription:
7574 type: string
7575 defaultClientRoute:
7576 type: string
7577 isNSFW:
7578 type: boolean
7579 defaultNSFWPolicy:
7580 type: string
7581 customizations:
7582 type: object
7583 properties:
7584 javascript:
7585 type: string
7586 css:
7587 type: string
7588 search:
7589 type: object
7590 properties:
7591 remoteUri:
7592 type: object
7593 properties:
7594 users:
7595 type: boolean
7596 anonymous:
7597 type: boolean
7598 plugin:
7599 type: object
7600 properties:
7601 registered:
7602 type: array
7603 items:
7604 type: string
7605 theme:
7606 type: object
7607 properties:
7608 registered:
7609 type: array
7610 items:
7611 type: string
7612 email:
7613 type: object
7614 properties:
7615 enabled:
7616 type: boolean
7617 contactForm:
7618 type: object
7619 properties:
7620 enabled:
7621 type: boolean
7622 serverVersion:
7623 type: string
7624 serverCommit:
7625 type: string
7626 signup:
7627 type: object
7628 properties:
7629 allowed:
7630 type: boolean
7631 allowedForCurrentIP:
7632 type: boolean
7633 requiresEmailVerification:
7634 type: boolean
7635 transcoding:
7636 type: object
7637 properties:
7638 hls:
7639 type: object
7640 properties:
7641 enabled:
7642 type: boolean
7643 webtorrent:
7644 type: object
7645 properties:
7646 enabled:
7647 type: boolean
7648 enabledResolutions:
7649 type: array
7650 items:
7651 $ref: '#/components/schemas/VideoResolutionSet'
7652 import:
7653 type: object
7654 properties:
7655 videos:
7656 type: object
7657 properties:
7658 http:
7659 type: object
7660 properties:
7661 enabled:
7662 type: boolean
7663 torrent:
7664 type: object
7665 properties:
7666 enabled:
7667 type: boolean
7668 videoChannelSynchronization:
7669 type: object
7670 properties:
7671 enabled:
7672 type: boolean
7673 autoBlacklist:
7674 type: object
7675 properties:
7676 videos:
7677 type: object
7678 properties:
7679 ofUsers:
7680 type: object
7681 properties:
7682 enabled:
7683 type: boolean
7684 avatar:
7685 type: object
7686 properties:
7687 file:
7688 type: object
7689 properties:
7690 size:
7691 type: object
7692 properties:
7693 max:
7694 type: integer
7695 extensions:
7696 type: array
7697 items:
7698 type: string
7699 video:
7700 type: object
7701 properties:
7702 image:
7703 type: object
7704 properties:
7705 extensions:
7706 type: array
7707 items:
7708 type: string
7709 size:
7710 type: object
7711 properties:
7712 max:
7713 type: integer
7714 file:
7715 type: object
7716 properties:
7717 extensions:
7718 type: array
7719 items:
7720 type: string
7721 videoCaption:
7722 type: object
7723 properties:
7724 file:
7725 type: object
7726 properties:
7727 size:
7728 type: object
7729 properties:
7730 max:
7731 type: integer
7732 extensions:
7733 type: array
7734 items:
7735 type: string
7736 user:
7737 type: object
7738 properties:
7739 videoQuota:
7740 type: integer
7741 example: 16810141515
7742 videoQuotaDaily:
7743 type: integer
7744 example: 1681014151
7745 trending:
7746 type: object
7747 properties:
7748 videos:
7749 type: object
7750 properties:
7751 intervalDays:
7752 type: integer
7753 tracker:
7754 type: object
7755 properties:
7756 enabled:
7757 type: boolean
7758 followings:
7759 type: object
7760 properties:
7761 instance:
7762 type: object
7763 properties:
7764 autoFollowIndex:
7765 type: object
7766 properties:
7767 indexUrl:
7768 type: string
7769 format: url
7770 homepage:
7771 type: object
7772 properties:
7773 enabled:
7774 type: boolean
7775
7776 SendClientLog:
7777 properties:
7778 message:
7779 type: string
7780 url:
7781 type: string
7782 description: URL of the current user page
7783 level:
7784 enum:
7785 - error
7786 - warn
7787 stackTrace:
7788 type: string
7789 description: Stack trace of the error if there is one
7790 userAgent:
7791 type: string
7792 description: User agent of the web browser that sends the message
7793 meta:
7794 type: string
7795 description: Additional information regarding this log
7796 required:
7797 - message
7798 - url
7799 - level
7800
7801 ServerStats:
7802 properties:
7803 totalUsers:
7804 type: number
7805 totalDailyActiveUsers:
7806 type: number
7807 totalWeeklyActiveUsers:
7808 type: number
7809 totalMonthlyActiveUsers:
7810 type: number
7811 totalLocalVideos:
7812 type: number
7813 totalLocalVideoViews:
7814 type: number
7815 description: Total video views made on the instance
7816 totalLocalVideoComments:
7817 type: number
7818 description: Total comments made by local users
7819 totalLocalVideoFilesSize:
7820 type: number
7821 totalVideos:
7822 type: number
7823 totalVideoComments:
7824 type: number
7825 totalLocalVideoChannels:
7826 type: number
7827 totalLocalDailyActiveVideoChannels:
7828 type: number
7829 totalLocalWeeklyActiveVideoChannels:
7830 type: number
7831 totalLocalMonthlyActiveVideoChannels:
7832 type: number
7833 totalLocalPlaylists:
7834 type: number
7835 totalInstanceFollowers:
7836 type: number
7837 totalInstanceFollowing:
7838 type: number
7839 videosRedundancy:
7840 type: array
7841 items:
7842 type: object
7843 properties:
7844 strategy:
7845 type: string
7846 totalSize:
7847 type: number
7848 totalUsed:
7849 type: number
7850 totalVideoFiles:
7851 type: number
7852 totalVideos:
7853 type: number
7854 totalActivityPubMessagesProcessed:
7855 type: number
7856 totalActivityPubMessagesSuccesses:
7857 type: number
7858 totalActivityPubMessagesErrors:
7859 type: number
7860
7861 activityPubMessagesProcessedPerSecond:
7862 type: number
7863 totalActivityPubMessagesWaiting:
7864 type: number
7865
7866 ServerConfigAbout:
7867 properties:
7868 instance:
7869 type: object
7870 properties:
7871 name:
7872 type: string
7873 shortDescription:
7874 type: string
7875 description:
7876 type: string
7877 terms:
7878 type: string
7879 ServerConfigCustom:
7880 properties:
7881 instance:
7882 type: object
7883 properties:
7884 name:
7885 type: string
7886 shortDescription:
7887 type: string
7888 description:
7889 type: string
7890 terms:
7891 type: string
7892 defaultClientRoute:
7893 type: string
7894 isNSFW:
7895 type: boolean
7896 defaultNSFWPolicy:
7897 type: string
7898 customizations:
7899 type: object
7900 properties:
7901 javascript:
7902 type: string
7903 css:
7904 type: string
7905 theme:
7906 type: object
7907 properties:
7908 default:
7909 type: string
7910 services:
7911 type: object
7912 properties:
7913 twitter:
7914 type: object
7915 properties:
7916 username:
7917 type: string
7918 whitelisted:
7919 type: boolean
7920 cache:
7921 type: object
7922 properties:
7923 previews:
7924 type: object
7925 properties:
7926 size:
7927 type: integer
7928 captions:
7929 type: object
7930 properties:
7931 size:
7932 type: integer
7933 signup:
7934 type: object
7935 properties:
7936 enabled:
7937 type: boolean
7938 limit:
7939 type: integer
7940 requiresEmailVerification:
7941 type: boolean
7942 admin:
7943 type: object
7944 properties:
7945 email:
7946 type: string
7947 format: email
7948 contactForm:
7949 type: object
7950 properties:
7951 enabled:
7952 type: boolean
7953 user:
7954 type: object
7955 description: Settings that apply to new users, if registration is enabled
7956 properties:
7957 videoQuota:
7958 type: integer
7959 example: 16810141515
7960 videoQuotaDaily:
7961 type: integer
7962 example: 1681014151
7963 transcoding:
7964 type: object
7965 description: Settings pertaining to transcoding jobs
7966 properties:
7967 enabled:
7968 type: boolean
7969 allowAdditionalExtensions:
7970 type: boolean
7971 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
7972 allowAudioFiles:
7973 type: boolean
7974 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
7975 threads:
7976 type: integer
7977 description: Amount of threads used by ffmpeg for 1 transcoding job
7978 concurrency:
7979 type: number
7980 description: Amount of transcoding jobs to execute in parallel
7981 profile:
7982 type: string
7983 enum:
7984 - default
7985 description: |
7986 New profiles can be added by plugins ; available in core PeerTube: 'default'.
7987 resolutions:
7988 type: object
7989 description: Resolutions to transcode _new videos_ to
7990 properties:
7991 0p:
7992 type: boolean
7993 144p:
7994 type: boolean
7995 240p:
7996 type: boolean
7997 360p:
7998 type: boolean
7999 480p:
8000 type: boolean
8001 720p:
8002 type: boolean
8003 1080p:
8004 type: boolean
8005 1440p:
8006 type: boolean
8007 2160p:
8008 type: boolean
8009 webtorrent:
8010 type: object
8011 description: WebTorrent-specific settings
8012 properties:
8013 enabled:
8014 type: boolean
8015 hls:
8016 type: object
8017 description: HLS-specific settings
8018 properties:
8019 enabled:
8020 type: boolean
8021 import:
8022 type: object
8023 properties:
8024 videos:
8025 type: object
8026 properties:
8027 http:
8028 type: object
8029 properties:
8030 enabled:
8031 type: boolean
8032 torrent:
8033 type: object
8034 properties:
8035 enabled:
8036 type: boolean
8037 video_channel_synchronization:
8038 type: object
8039 properties:
8040 enabled:
8041 type: boolean
8042 autoBlacklist:
8043 type: object
8044 properties:
8045 videos:
8046 type: object
8047 properties:
8048 ofUsers:
8049 type: object
8050 properties:
8051 enabled:
8052 type: boolean
8053 followers:
8054 type: object
8055 properties:
8056 instance:
8057 type: object
8058 properties:
8059 enabled:
8060 type: boolean
8061 manualApproval:
8062 type: boolean
8063
8064 CustomHomepage:
8065 properties:
8066 content:
8067 type: string
8068
8069 Follow:
8070 properties:
8071 id:
8072 $ref: '#/components/schemas/id'
8073 follower:
8074 $ref: '#/components/schemas/Actor'
8075 following:
8076 $ref: '#/components/schemas/Actor'
8077 score:
8078 type: number
8079 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
8080 state:
8081 type: string
8082 enum:
8083 - pending
8084 - accepted
8085 createdAt:
8086 type: string
8087 format: date-time
8088 updatedAt:
8089 type: string
8090 format: date-time
8091
8092 PredefinedAbuseReasons:
8093 description: Reason categories that help triage reports
8094 type: array
8095 maxItems: 8
8096 items:
8097 type: string
8098 enum:
8099 - violentOrAbusive
8100 - hatefulOrAbusive
8101 - spamOrMisleading
8102 - privacy
8103 - rights
8104 - serverRules
8105 - thumbnails
8106 - captions
8107
8108 Job:
8109 properties:
8110 id:
8111 $ref: '#/components/schemas/id'
8112 state:
8113 type: string
8114 enum:
8115 - active
8116 - completed
8117 - failed
8118 - waiting
8119 - delayed
8120 type:
8121 type: string
8122 enum:
8123 - activitypub-http-unicast
8124 - activitypub-http-broadcast
8125 - activitypub-http-fetcher
8126 - activitypub-follow
8127 - video-file-import
8128 - video-transcoding
8129 - email
8130 - video-import
8131 - videos-views-stats
8132 - activitypub-refresher
8133 - video-redundancy
8134 - video-channel-import
8135 data:
8136 type: object
8137 additionalProperties: true
8138 error:
8139 type: object
8140 additionalProperties: true
8141 createdAt:
8142 type: string
8143 format: date-time
8144 finishedOn:
8145 type: string
8146 format: date-time
8147 processedOn:
8148 type: string
8149 format: date-time
8150 AddUserResponse:
8151 properties:
8152 user:
8153 type: object
8154 properties:
8155 id:
8156 $ref: '#/components/schemas/id'
8157 account:
8158 type: object
8159 properties:
8160 id:
8161 $ref: '#/components/schemas/id'
8162 VideoUploadRequestCommon:
8163 properties:
8164 name:
8165 description: Video name
8166 type: string
8167 example: What is PeerTube?
8168 minLength: 3
8169 maxLength: 120
8170 channelId:
8171 description: Channel id that will contain this video
8172 type: integer
8173 example: 3
8174 minimum: 1
8175 privacy:
8176 $ref: '#/components/schemas/VideoPrivacySet'
8177 category:
8178 $ref: '#/components/schemas/VideoCategorySet'
8179 licence:
8180 $ref: '#/components/schemas/VideoLicenceSet'
8181 language:
8182 $ref: '#/components/schemas/VideoLanguageSet'
8183 description:
8184 description: Video description
8185 type: string
8186 example: |
8187 **[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)**
8188 waitTranscoding:
8189 description: Whether or not we wait transcoding before publish the video
8190 type: boolean
8191 support:
8192 description: A text tell the audience how to support the video creator
8193 example: Please support our work on https://soutenir.framasoft.org/en/ <3
8194 type: string
8195 nsfw:
8196 description: Whether or not this video contains sensitive content
8197 type: boolean
8198 tags:
8199 description: Video tags (maximum 5 tags each between 2 and 30 characters)
8200 type: array
8201 minItems: 1
8202 maxItems: 5
8203 uniqueItems: true
8204 example:
8205 - framasoft
8206 - peertube
8207 items:
8208 type: string
8209 minLength: 2
8210 maxLength: 30
8211 commentsEnabled:
8212 description: Enable or disable comments for this video
8213 type: boolean
8214 downloadEnabled:
8215 description: Enable or disable downloading for this video
8216 type: boolean
8217 originallyPublishedAt:
8218 description: Date when the content was originally published
8219 type: string
8220 format: date-time
8221 scheduleUpdate:
8222 $ref: '#/components/schemas/VideoScheduledUpdate'
8223 thumbnailfile:
8224 description: Video thumbnail file
8225 type: string
8226 format: binary
8227 previewfile:
8228 description: Video preview file
8229 type: string
8230 format: binary
8231 required:
8232 - channelId
8233 - name
8234 VideoUploadRequestLegacy:
8235 allOf:
8236 - $ref: '#/components/schemas/VideoUploadRequestCommon'
8237 - type: object
8238 required:
8239 - videofile
8240 properties:
8241 videofile:
8242 description: Video file
8243 type: string
8244 format: binary
8245 VideoUploadRequestResumable:
8246 allOf:
8247 - $ref: '#/components/schemas/VideoUploadRequestCommon'
8248 - type: object
8249 required:
8250 - filename
8251 properties:
8252 filename:
8253 description: Video filename including extension
8254 type: string
8255 format: filename
8256 example: what_is_peertube.mp4
8257 thumbnailfile:
8258 description: Video thumbnail file
8259 type: string
8260 format: binary
8261 previewfile:
8262 description: Video preview file
8263 type: string
8264 format: binary
8265 VideoUploadResponse:
8266 properties:
8267 video:
8268 type: object
8269 properties:
8270 id:
8271 $ref: '#/components/schemas/Video/properties/id'
8272 uuid:
8273 $ref: '#/components/schemas/Video/properties/uuid'
8274 shortUUID:
8275 $ref: '#/components/schemas/Video/properties/shortUUID'
8276 CommentThreadResponse:
8277 properties:
8278 total:
8279 type: integer
8280 example: 1
8281 data:
8282 type: array
8283 maxItems: 100
8284 items:
8285 $ref: '#/components/schemas/VideoComment'
8286 CommentThreadPostResponse:
8287 properties:
8288 comment:
8289 $ref: '#/components/schemas/VideoComment'
8290 VideoTokenResponse:
8291 properties:
8292 files:
8293 type: object
8294 properties:
8295 token:
8296 type: string
8297 expires:
8298 type: string
8299 format: date-time
8300 VideoListResponse:
8301 properties:
8302 total:
8303 type: integer
8304 example: 1
8305 data:
8306 type: array
8307 maxItems: 100
8308 items:
8309 $ref: '#/components/schemas/Video'
8310 User:
8311 properties:
8312 account:
8313 $ref: '#/components/schemas/Account'
8314 autoPlayNextVideo:
8315 type: boolean
8316 description: Automatically start playing the upcoming video after the currently playing video
8317 autoPlayNextVideoPlaylist:
8318 type: boolean
8319 description: Automatically start playing the video on the playlist after the currently playing video
8320 autoPlayVideo:
8321 type: boolean
8322 description: Automatically start playing the video on the watch page
8323 blocked:
8324 type: boolean
8325 blockedReason:
8326 type: string
8327 createdAt:
8328 type: string
8329 email:
8330 type: string
8331 format: email
8332 description: The user email
8333 emailVerified:
8334 type: boolean
8335 description: Has the user confirmed their email address?
8336 id:
8337 allOf:
8338 - $ref: '#/components/schemas/id'
8339 readOnly: true
8340 pluginAuth:
8341 type: string
8342 description: Auth plugin to use to authenticate the user
8343 lastLoginDate:
8344 type: string
8345 format: date-time
8346 noInstanceConfigWarningModal:
8347 type: boolean
8348 noAccountSetupWarningModal:
8349 type: boolean
8350 noWelcomeModal:
8351 type: boolean
8352 nsfwPolicy:
8353 $ref: '#/components/schemas/NSFWPolicy'
8354 role:
8355 type: object
8356 properties:
8357 id:
8358 $ref: '#/components/schemas/UserRole'
8359 label:
8360 type: string
8361 enum:
8362 - User
8363 - Moderator
8364 - Administrator
8365 theme:
8366 type: string
8367 description: Theme enabled by this user
8368 username:
8369 $ref: '#/components/schemas/username'
8370 videoChannels:
8371 type: array
8372 items:
8373 $ref: '#/components/schemas/VideoChannel'
8374 videoQuota:
8375 type: integer
8376 description: The user video quota in bytes
8377 example: -1
8378 videoQuotaDaily:
8379 type: integer
8380 description: The user daily video quota in bytes
8381 example: -1
8382 p2pEnabled:
8383 type: boolean
8384 description: Enable P2P in the player
8385 UserWithStats:
8386 allOf:
8387 - $ref: '#/components/schemas/User'
8388 - properties:
8389 # optionally present fields: they require WITH_STATS scope
8390 videosCount:
8391 type: integer
8392 description: Count of videos published
8393 abusesCount:
8394 type: integer
8395 description: Count of reports/abuses of which the user is a target
8396 abusesAcceptedCount:
8397 type: integer
8398 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
8399 abusesCreatedCount:
8400 type: integer
8401 description: Count of reports/abuses created by the user
8402 videoCommentsCount:
8403 type: integer
8404 description: Count of comments published
8405 AddUser:
8406 properties:
8407 username:
8408 $ref: '#/components/schemas/username'
8409 password:
8410 $ref: '#/components/schemas/password'
8411 email:
8412 type: string
8413 format: email
8414 description: The user email
8415 videoQuota:
8416 type: integer
8417 description: The user video quota in bytes
8418 example: -1
8419 videoQuotaDaily:
8420 type: integer
8421 description: The user daily video quota in bytes
8422 example: -1
8423 channelName:
8424 $ref: '#/components/schemas/usernameChannel'
8425 role:
8426 $ref: '#/components/schemas/UserRole'
8427 adminFlags:
8428 $ref: '#/components/schemas/UserAdminFlags'
8429 required:
8430 - username
8431 - password
8432 - email
8433 - role
8434 UpdateUser:
8435 properties:
8436 email:
8437 description: The updated email of the user
8438 allOf:
8439 - $ref: '#/components/schemas/User/properties/email'
8440 emailVerified:
8441 type: boolean
8442 description: Set the email as verified
8443 videoQuota:
8444 type: integer
8445 description: The updated video quota of the user in bytes
8446 videoQuotaDaily:
8447 type: integer
8448 description: The updated daily video quota of the user in bytes
8449 pluginAuth:
8450 type: string
8451 nullable: true
8452 description: The auth plugin to use to authenticate the user
8453 example: 'peertube-plugin-auth-saml2'
8454 role:
8455 $ref: '#/components/schemas/UserRole'
8456 adminFlags:
8457 $ref: '#/components/schemas/UserAdminFlags'
8458 password:
8459 $ref: '#/components/schemas/password'
8460 UpdateMe:
8461 # see shared/models/users/user-update-me.model.ts:
8462 properties:
8463 password:
8464 $ref: '#/components/schemas/password'
8465 currentPassword:
8466 $ref: '#/components/schemas/password'
8467 email:
8468 description: new email used for login and service communications
8469 allOf:
8470 - $ref: '#/components/schemas/User/properties/email'
8471 displayName:
8472 type: string
8473 description: new name of the user in its representations
8474 minLength: 3
8475 maxLength: 120
8476 displayNSFW:
8477 type: string
8478 description: new NSFW display policy
8479 enum:
8480 - 'true'
8481 - 'false'
8482 - both
8483 p2pEnabled:
8484 type: boolean
8485 description: whether to enable P2P in the player or not
8486 autoPlayVideo:
8487 type: boolean
8488 description: new preference regarding playing videos automatically
8489 autoPlayNextVideo:
8490 type: boolean
8491 description: new preference regarding playing following videos automatically
8492 autoPlayNextVideoPlaylist:
8493 type: boolean
8494 description: new preference regarding playing following playlist videos automatically
8495 videosHistoryEnabled:
8496 type: boolean
8497 description: whether to keep track of watched history or not
8498 videoLanguages:
8499 type: array
8500 items:
8501 type: string
8502 description: list of languages to filter videos down to
8503 theme:
8504 type: string
8505 noInstanceConfigWarningModal:
8506 type: boolean
8507 noAccountSetupWarningModal:
8508 type: boolean
8509 noWelcomeModal:
8510 type: boolean
8511 GetMeVideoRating:
8512 properties:
8513 id:
8514 $ref: '#/components/schemas/id'
8515 rating:
8516 type: string
8517 enum:
8518 - like
8519 - dislike
8520 - none
8521 description: Rating of the video
8522 required:
8523 - id
8524 - rating
8525 VideoRating:
8526 properties:
8527 video:
8528 $ref: '#/components/schemas/Video'
8529 rating:
8530 type: string
8531 enum:
8532 - like
8533 - dislike
8534 - none
8535 description: Rating of the video
8536 required:
8537 - video
8538 - rating
8539
8540 RegisterUser:
8541 properties:
8542 username:
8543 description: immutable name of the user, used to find or mention its actor
8544 allOf:
8545 - $ref: '#/components/schemas/username'
8546 password:
8547 $ref: '#/components/schemas/password'
8548 email:
8549 type: string
8550 format: email
8551 description: email of the user, used for login or service communications
8552 displayName:
8553 type: string
8554 description: editable name of the user, displayed in its representations
8555 minLength: 1
8556 maxLength: 120
8557 channel:
8558 type: object
8559 description: channel base information used to create the first channel of the user
8560 properties:
8561 name:
8562 $ref: '#/components/schemas/usernameChannel'
8563 displayName:
8564 type: string
8565 required:
8566 - username
8567 - password
8568 - email
8569
8570 UserRegistrationRequest:
8571 allOf:
8572 - $ref: '#/components/schemas/RegisterUser'
8573 - type: object
8574 properties:
8575 registrationReason:
8576 type: string
8577 description: reason for the user to register on the instance
8578 required:
8579 - registrationReason
8580
8581 UserRegistrationAcceptOrReject:
8582 type: object
8583 properties:
8584 moderationResponse:
8585 type: string
8586 description: Moderation response to send to the user
8587 preventEmailDelivery:
8588 type: boolean
8589 description: Set it to true if you don't want PeerTube to send an email to the user
8590 required:
8591 - moderationResponse
8592
8593 UserRegistration:
8594 properties:
8595 id:
8596 $ref: '#/components/schemas/id'
8597 state:
8598 type: object
8599 properties:
8600 id:
8601 type: integer
8602 enum:
8603 - 1
8604 - 2
8605 - 3
8606 description: 'The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
8607 label:
8608 type: string
8609 registrationReason:
8610 type: string
8611 moderationResponse:
8612 type: string
8613 nullable: true
8614 username:
8615 type: string
8616 email:
8617 type: string
8618 format: email
8619 emailVerified:
8620 type: boolean
8621 accountDisplayName:
8622 type: string
8623 channelHandle:
8624 type: string
8625 channelDisplayName:
8626 type: string
8627 createdAt:
8628 type: string
8629 format: date-time
8630 updatedAt:
8631 type: string
8632 format: date-time
8633 user:
8634 type: object
8635 nullable: true
8636 description: If the registration has been accepted, this is a partial user object created by the registration
8637 properties:
8638 id:
8639 $ref: '#/components/schemas/id'
8640
8641 OAuthClient:
8642 properties:
8643 client_id:
8644 type: string
8645 pattern: /^[a-z0-9]$/
8646 maxLength: 32
8647 minLength: 32
8648 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
8649 client_secret:
8650 type: string
8651 pattern: /^[a-zA-Z0-9]$/
8652 maxLength: 32
8653 minLength: 32
8654 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
8655 OAuthToken-password:
8656 allOf:
8657 - $ref: '#/components/schemas/OAuthClient'
8658 - type: object
8659 properties:
8660 grant_type:
8661 type: string
8662 enum:
8663 - password
8664 - refresh_token
8665 default: password
8666 username:
8667 $ref: '#/components/schemas/User/properties/username'
8668 password:
8669 $ref: '#/components/schemas/password'
8670 required:
8671 - client_id
8672 - client_secret
8673 - grant_type
8674 - username
8675 - password
8676 OAuthToken-refresh_token:
8677 allOf:
8678 - $ref: '#/components/schemas/OAuthClient'
8679 - type: object
8680 properties:
8681 grant_type:
8682 type: string
8683 enum:
8684 - password
8685 - refresh_token
8686 default: password
8687 refresh_token:
8688 type: string
8689 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
8690 required:
8691 - client_id
8692 - client_secret
8693 - grant_type
8694 - refresh_token
8695
8696 VideoChannel:
8697 allOf:
8698 - $ref: '#/components/schemas/Actor'
8699 - type: object
8700 properties:
8701 displayName:
8702 type: string
8703 description: editable name of the channel, displayed in its representations
8704 example: Videos of Framasoft
8705 minLength: 1
8706 maxLength: 120
8707 description:
8708 type: string
8709 example: Videos made with <3 by Framasoft
8710 minLength: 3
8711 maxLength: 1000
8712 support:
8713 type: string
8714 description: text shown by default on all videos of this channel, to tell the audience how to support it
8715 example: Please support our work on https://soutenir.framasoft.org/en/ <3
8716 minLength: 3
8717 maxLength: 1000
8718 isLocal:
8719 readOnly: true
8720 type: boolean
8721 updatedAt:
8722 readOnly: true
8723 type: string
8724 format: date-time
8725 banners:
8726 type: array
8727 items:
8728 $ref: '#/components/schemas/ActorImage'
8729 ownerAccount:
8730 readOnly: true
8731 nullable: true
8732 type: object
8733 properties:
8734 id:
8735 type: integer
8736 uuid:
8737 $ref: '#/components/schemas/UUIDv4'
8738
8739 VideoChannelEdit:
8740 properties:
8741 displayName:
8742 description: Channel display name
8743 description:
8744 description: Channel description
8745 support:
8746 description: How to support/fund the channel
8747
8748 VideoChannelCreate:
8749 allOf:
8750 - $ref: '#/components/schemas/VideoChannelEdit'
8751 - properties:
8752 name:
8753 description: username of the channel to create
8754 allOf:
8755 - $ref: '#/components/schemas/usernameChannel'
8756 required:
8757 - name
8758 - displayName
8759 VideoChannelUpdate:
8760 allOf:
8761 - $ref: '#/components/schemas/VideoChannelEdit'
8762 - properties:
8763 bulkVideosSupportUpdate:
8764 type: boolean
8765 description: Update the support field for all videos of this channel
8766
8767 VideoChannelList:
8768 properties:
8769 total:
8770 type: integer
8771 example: 1
8772 data:
8773 type: array
8774 items:
8775 allOf:
8776 - $ref: '#/components/schemas/VideoChannel'
8777 - $ref: '#/components/schemas/Actor'
8778
8779 ImportVideosInChannelCreate:
8780 type: object
8781 properties:
8782 externalChannelUrl:
8783 type: string
8784 example: https://youtube.com/c/UC_myfancychannel
8785 videoChannelSyncId:
8786 type: integer
8787 description: If part of a channel sync process, specify its id to assign video imports to this channel synchronization
8788 required:
8789 - 'externalChannelUrl'
8790
8791 VideoChannelSync:
8792 type: object
8793 properties:
8794 id:
8795 $ref: '#/components/schemas/id'
8796 state:
8797 type: object
8798 properties:
8799 id:
8800 type: integer
8801 example: 2
8802 label:
8803 type: string
8804 example: PROCESSING
8805 externalChannelUrl:
8806 type: string
8807 example: 'https://youtube.com/c/UC_myfancychannel'
8808 createdAt:
8809 type: string
8810 format: date-time
8811 lastSyncAt:
8812 type: string
8813 format: date-time
8814 nullable: true
8815 channel:
8816 $ref: '#/components/schemas/VideoChannel'
8817 VideoChannelSyncList:
8818 type: object
8819 properties:
8820 total:
8821 type: integer
8822 example: 1
8823 data:
8824 type: array
8825 items:
8826 allOf:
8827 - $ref: '#/components/schemas/VideoChannelSync'
8828 VideoChannelSyncCreate:
8829 type: object
8830 properties:
8831 externalChannelUrl:
8832 type: string
8833 example: https://youtube.com/c/UC_myfancychannel
8834 videoChannelId:
8835 $ref: '#/components/schemas/id'
8836 MRSSPeerLink:
8837 type: object
8838 xml:
8839 name: 'media:peerLink'
8840 properties:
8841 href:
8842 type: string
8843 xml:
8844 attribute: true
8845 type:
8846 type: string
8847 enum:
8848 - application/x-bittorrent
8849 xml:
8850 attribute: true
8851 MRSSGroupContent:
8852 type: object
8853 xml:
8854 name: 'media:content'
8855 properties:
8856 url:
8857 type: string
8858 format: url
8859 xml:
8860 attribute: true
8861 fileSize:
8862 type: integer
8863 xml:
8864 attribute: true
8865 type:
8866 type: string
8867 xml:
8868 attribute: true
8869 framerate:
8870 type: integer
8871 xml:
8872 attribute: true
8873 duration:
8874 type: integer
8875 xml:
8876 attribute: true
8877 height:
8878 type: integer
8879 xml:
8880 attribute: true
8881 lang:
8882 type: string
8883 xml:
8884 attribute: true
8885 VideoCommentsForXML:
8886 type: array
8887 xml:
8888 wrapped: true
8889 name: 'channel'
8890 items:
8891 type: object
8892 xml:
8893 name: 'item'
8894 properties:
8895 link:
8896 type: string
8897 format: url
8898 guid:
8899 type: string
8900 pubDate:
8901 type: string
8902 format: date-time
8903 'content:encoded':
8904 type: string
8905 'dc:creator':
8906 type: string
8907 VideosForXML:
8908 type: array
8909 xml:
8910 wrapped: true
8911 name: 'channel'
8912 items:
8913 type: object
8914 xml:
8915 name: 'item'
8916 properties:
8917 link:
8918 type: string
8919 format: url
8920 description: video watch page URL
8921 guid:
8922 type: string
8923 description: video canonical URL
8924 pubDate:
8925 type: string
8926 format: date-time
8927 description: video publication date
8928 description:
8929 type: string
8930 description: video description
8931 'content:encoded':
8932 type: string
8933 description: video description
8934 'dc:creator':
8935 type: string
8936 description: publisher user name
8937 'media:category':
8938 type: integer
8939 description: video category (MRSS)
8940 'media:community':
8941 type: object
8942 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
8943 properties:
8944 'media:statistics':
8945 type: object
8946 properties:
8947 views:
8948 type: integer
8949 xml:
8950 attribute: true
8951 'media:embed':
8952 type: object
8953 properties:
8954 url:
8955 type: string
8956 format: url
8957 description: video embed path, relative to the canonical URL domain (MRSS)
8958 xml:
8959 attribute: true
8960 'media:player':
8961 type: object
8962 properties:
8963 url:
8964 type: string
8965 format: url
8966 description: video watch path, relative to the canonical URL domain (MRSS)
8967 xml:
8968 attribute: true
8969 'media:thumbnail':
8970 type: object
8971 properties:
8972 url:
8973 type: string
8974 format: url
8975 xml:
8976 attribute: true
8977 height:
8978 type: integer
8979 xml:
8980 attribute: true
8981 width:
8982 type: integer
8983 xml:
8984 attribute: true
8985 'media:title':
8986 type: string
8987 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
8988 'media:description':
8989 type: string
8990 'media:rating':
8991 type: string
8992 enum:
8993 - nonadult
8994 - adult
8995 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
8996 'enclosure':
8997 type: object
8998 description: main streamable file for the video
8999 properties:
9000 url:
9001 type: string
9002 format: url
9003 xml:
9004 attribute: true
9005 type:
9006 type: string
9007 enum:
9008 - application/x-bittorrent
9009 xml:
9010 attribute: true
9011 length:
9012 type: integer
9013 xml:
9014 attribute: true
9015 'media:group':
9016 type: array
9017 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)
9018 items:
9019 anyOf:
9020 - $ref: '#/components/schemas/MRSSPeerLink'
9021 - $ref: '#/components/schemas/MRSSGroupContent'
9022 NotificationSettingValue:
9023 type: integer
9024 description: >
9025 Notification type. One of the following values, or a sum of multiple values:
9026
9027 - `0` NONE
9028
9029 - `1` WEB
9030
9031 - `2` EMAIL
9032 Notification:
9033 properties:
9034 id:
9035 $ref: '#/components/schemas/id'
9036 type:
9037 type: integer
9038 description: >
9039 Notification type, following the `UserNotificationType` enum:
9040
9041 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
9042
9043 - `2` NEW_COMMENT_ON_MY_VIDEO
9044
9045 - `3` NEW_ABUSE_FOR_MODERATORS
9046
9047 - `4` BLACKLIST_ON_MY_VIDEO
9048
9049 - `5` UNBLACKLIST_ON_MY_VIDEO
9050
9051 - `6` MY_VIDEO_PUBLISHED
9052
9053 - `7` MY_VIDEO_IMPORT_SUCCESS
9054
9055 - `8` MY_VIDEO_IMPORT_ERROR
9056
9057 - `9` NEW_USER_REGISTRATION
9058
9059 - `10` NEW_FOLLOW
9060
9061 - `11` COMMENT_MENTION
9062
9063 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
9064
9065 - `13` NEW_INSTANCE_FOLLOWER
9066
9067 - `14` AUTO_INSTANCE_FOLLOWING
9068
9069 - `15` ABUSE_STATE_CHANGE
9070
9071 - `16` ABUSE_NEW_MESSAGE
9072
9073 - `17` NEW_PLUGIN_VERSION
9074
9075 - `18` NEW_PEERTUBE_VERSION
9076 read:
9077 type: boolean
9078 video:
9079 nullable: true
9080 allOf:
9081 - $ref: '#/components/schemas/VideoInfo'
9082 - type: object
9083 properties:
9084 channel:
9085 $ref: '#/components/schemas/ActorInfo'
9086 videoImport:
9087 nullable: true
9088 type: object
9089 properties:
9090 id:
9091 $ref: '#/components/schemas/id'
9092 video:
9093 nullable: true
9094 $ref: '#/components/schemas/VideoInfo'
9095 torrentName:
9096 type: string
9097 nullable: true
9098 magnetUri:
9099 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
9100 targetUri:
9101 type: string
9102 format: uri
9103 nullable: true
9104 comment:
9105 nullable: true
9106 type: object
9107 properties:
9108 id:
9109 $ref: '#/components/schemas/id'
9110 threadId:
9111 type: integer
9112 video:
9113 $ref: '#/components/schemas/VideoInfo'
9114 account:
9115 $ref: '#/components/schemas/ActorInfo'
9116 videoAbuse:
9117 nullable: true
9118 type: object
9119 properties:
9120 id:
9121 $ref: '#/components/schemas/id'
9122 video:
9123 allOf:
9124 - $ref: '#/components/schemas/VideoInfo'
9125 videoBlacklist:
9126 nullable: true
9127 type: object
9128 properties:
9129 id:
9130 $ref: '#/components/schemas/id'
9131 video:
9132 allOf:
9133 - $ref: '#/components/schemas/VideoInfo'
9134 account:
9135 nullable: true
9136 allOf:
9137 - $ref: '#/components/schemas/ActorInfo'
9138 actorFollow:
9139 type: object
9140 nullable: true
9141 properties:
9142 id:
9143 $ref: '#/components/schemas/id'
9144 follower:
9145 $ref: '#/components/schemas/ActorInfo'
9146 state:
9147 type: string
9148 enum:
9149 - pending
9150 - accepted
9151 following:
9152 type: object
9153 properties:
9154 type:
9155 type: string
9156 enum:
9157 - account
9158 - channel
9159 - instance
9160 name:
9161 type: string
9162 displayName:
9163 type: string
9164 host:
9165 type: string
9166 format: hostname
9167 createdAt:
9168 type: string
9169 format: date-time
9170 updatedAt:
9171 type: string
9172 format: date-time
9173 NotificationListResponse:
9174 properties:
9175 total:
9176 type: integer
9177 example: 1
9178 data:
9179 type: array
9180 maxItems: 100
9181 items:
9182 $ref: '#/components/schemas/Notification'
9183 Plugin:
9184 properties:
9185 name:
9186 type: string
9187 example: peertube-plugin-auth-ldap
9188 type:
9189 type: integer
9190 description: >
9191 - `1`: PLUGIN
9192
9193 - `2`: THEME
9194 enum:
9195 - 1
9196 - 2
9197 latestVersion:
9198 type: string
9199 example: 0.0.3
9200 version:
9201 type: string
9202 example: 0.0.1
9203 enabled:
9204 type: boolean
9205 uninstalled:
9206 type: boolean
9207 peertubeEngine:
9208 type: string
9209 example: 2.2.0
9210 description:
9211 type: string
9212 homepage:
9213 type: string
9214 format: url
9215 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
9216 settings:
9217 type: object
9218 additionalProperties: true
9219 createdAt:
9220 type: string
9221 format: date-time
9222 updatedAt:
9223 type: string
9224 format: date-time
9225 PluginResponse:
9226 properties:
9227 total:
9228 type: integer
9229 example: 1
9230 data:
9231 type: array
9232 maxItems: 100
9233 items:
9234 $ref: '#/components/schemas/Plugin'
9235
9236 LiveVideoUpdate:
9237 properties:
9238 saveReplay:
9239 type: boolean
9240 replaySettings:
9241 $ref: '#/components/schemas/LiveVideoReplaySettings'
9242 permanentLive:
9243 description: User can stream multiple times in a permanent live
9244 type: boolean
9245 latencyMode:
9246 description: User can select live latency mode if enabled by the instance
9247 $ref: '#/components/schemas/LiveVideoLatencyMode'
9248
9249 LiveVideoResponse:
9250 properties:
9251 rtmpUrl:
9252 type: string
9253 description: Included in the response if an appropriate token is provided
9254 rtmpsUrl:
9255 type: string
9256 description: Included in the response if an appropriate token is provided
9257 streamKey:
9258 type: string
9259 description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
9260 saveReplay:
9261 type: boolean
9262 replaySettings:
9263 $ref: '#/components/schemas/LiveVideoReplaySettings'
9264 permanentLive:
9265 description: User can stream multiple times in a permanent live
9266 type: boolean
9267 latencyMode:
9268 description: User can select live latency mode if enabled by the instance
9269 $ref: '#/components/schemas/LiveVideoLatencyMode'
9270
9271 RequestTwoFactorResponse:
9272 properties:
9273 otpRequest:
9274 type: object
9275 properties:
9276 requestToken:
9277 type: string
9278 description: The token to send to confirm this request
9279 secret:
9280 type: string
9281 description: The OTP secret
9282 uri:
9283 type: string
9284 description: The OTP URI
9285
9286 VideoStudioCreateTask:
9287 type: array
9288 items:
9289 anyOf:
9290 -
9291 title: cut
9292 type: object
9293 properties:
9294 name:
9295 type: string
9296 enum:
9297 - 'cut'
9298 options:
9299 type: object
9300 properties:
9301 start:
9302 type: integer
9303 end:
9304 type: integer
9305 -
9306 title: add-intro
9307 type: object
9308 properties:
9309 name:
9310 type: string
9311 enum:
9312 - 'add-intro'
9313 options:
9314 type: object
9315 properties:
9316 file:
9317 type: string
9318 format: binary
9319 -
9320 title: add-outro
9321 type: object
9322 properties:
9323 name:
9324 type: string
9325 enum:
9326 - 'add-outro'
9327 options:
9328 type: object
9329 properties:
9330 file:
9331 type: string
9332 format: binary
9333 -
9334 title: add-watermark
9335 type: object
9336 properties:
9337 name:
9338 type: string
9339 enum:
9340 - 'add-watermark'
9341 options:
9342 type: object
9343 properties:
9344 file:
9345 type: string
9346 format: binary
9347
9348 LiveVideoSessionResponse:
9349 properties:
9350 id:
9351 type: integer
9352 startDate:
9353 type: string
9354 format: date-time
9355 description: Start date of the live session
9356 endDate:
9357 type: string
9358 format: date-time
9359 nullable: true
9360 description: End date of the live session
9361 error:
9362 type: integer
9363 enum:
9364 - 1
9365 - 2
9366 - 3
9367 - 4
9368 - 5
9369 nullable: true
9370 description: >
9371 Error type if an error occurred during the live session:
9372 - `1`: Bad socket health (transcoding is too slow)
9373 - `2`: Max duration exceeded
9374 - `3`: Quota exceeded
9375 - `4`: Quota FFmpeg error
9376 - `5`: Video has been blacklisted during the live
9377 replayVideo:
9378 type: object
9379 description: Video replay information
9380 properties:
9381 id:
9382 type: number
9383 uuid:
9384 $ref: '#/components/schemas/UUIDv4'
9385 shortUUID:
9386 $ref: '#/components/schemas/shortUUID'
9387
9388 PlaybackMetricCreate:
9389 properties:
9390 playerMode:
9391 type: string
9392 enum:
9393 - 'p2p-media-loader'
9394 - 'webtorrent'
9395 resolution:
9396 type: number
9397 description: Current player video resolution
9398 fps:
9399 type: number
9400 description: Current player video fps
9401 resolutionChanges:
9402 type: number
9403 description: How many resolution changes occured since the last metric creation
9404 errors:
9405 type: number
9406 description: How many errors occured since the last metric creation
9407 downloadedBytesP2P:
9408 type: number
9409 description: How many bytes were downloaded with P2P since the last metric creation
9410 downloadedBytesHTTP:
9411 type: number
9412 description: How many bytes were downloaded with HTTP since the last metric creation
9413 uploadedBytesP2P:
9414 type: number
9415 description: How many bytes were uploaded with P2P since the last metric creation
9416 videoId:
9417 oneOf:
9418 - $ref: '#/components/schemas/id'
9419 - $ref: '#/components/schemas/UUIDv4'
9420 - $ref: '#/components/schemas/shortUUID'
9421 required:
9422 - playerMode
9423 - resolutionChanges
9424 - errors
9425 - downloadedBytesP2P
9426 - downloadedBytesHTTP
9427 - uploadedBytesP2P
9428 - videoId
9429
9430 RunnerRegistrationToken:
9431 properties:
9432 id:
9433 type: integer
9434 registrationToken:
9435 type: string
9436 createdAt:
9437 type: string
9438 format: date-time
9439 updatedAt:
9440 type: string
9441 format: date-time
9442 registeredRunnersCount:
9443 type: integer
9444
9445 Runner:
9446 properties:
9447 id:
9448 type: integer
9449 name:
9450 type: string
9451 description:
9452 type: string
9453 ip:
9454 type: string
9455 updatedAt:
9456 type: string
9457 format: date-time
9458 createdAt:
9459 type: string
9460 format: date-time
9461 lastContact:
9462 type: string
9463 format: date-time
9464
9465 RunnerJobType:
9466 type: string
9467 enum:
9468 - vod-web-video-transcoding
9469 - vod-hls-transcoding
9470 - vod-audio-merge-transcoding
9471 - live-rtmp-hls-transcoding
9472
9473 RunnerJobState:
9474 type: integer
9475 enum:
9476 - 1
9477 - 2
9478 - 3
9479 - 4
9480 - 5
9481 - 6
9482 - 7
9483 - 8
9484 description: >
9485 The runner job state:
9486 - `1` Pending
9487 - `2` Processing
9488 - `3` Completed
9489 - `4` Errored
9490 - `5` Waiting for a parent job
9491 - `6` Cancelled
9492 - `7` Parent had an error
9493 - `8` Parent has been cancelled
9494
9495 RunnerJobStateConstant:
9496 type: object
9497 properties:
9498 id:
9499 $ref: '#/components/schemas/RunnerJobState'
9500 label:
9501 type: string
9502 example: 'Processing'
9503
9504 RunnerJobPayload:
9505 anyOf:
9506 - type: object
9507 title: VOD web video transcoding
9508 properties:
9509 input:
9510 type: object
9511 properties:
9512 videoFileUrl:
9513 type: string
9514 output:
9515 type: object
9516 properties:
9517 resolution:
9518 type: number
9519 fps:
9520 type: number
9521 - type: object
9522 title: VOD HLS transcoding
9523 properties:
9524 input:
9525 type: object
9526 properties:
9527 videoFileUrl:
9528 type: string
9529 output:
9530 type: object
9531 properties:
9532 resolution:
9533 type: number
9534 fps:
9535 type: number
9536 - type: object
9537 title: VOD audio merge transcoding
9538 properties:
9539 input:
9540 type: object
9541 properties:
9542 audioFileUrl:
9543 type: string
9544 previewFileUrl:
9545 type: string
9546 output:
9547 type: object
9548 properties:
9549 resolution:
9550 type: number
9551 fps:
9552 type: number
9553
9554 RunnerJob:
9555 properties:
9556 uuid:
9557 $ref: '#/components/schemas/UUIDv4'
9558 type:
9559 $ref: '#/components/schemas/RunnerJobType'
9560 state:
9561 $ref: '#/components/schemas/RunnerJobStateConstant'
9562 payload:
9563 $ref: '#/components/schemas/RunnerJobPayload'
9564 failures:
9565 type: integer
9566 description: Number of times a remote runner failed to process this job. After too many failures, the job in "error" state
9567 error:
9568 nullable: true
9569 type: string
9570 description: Error message if the job is errored
9571 progress:
9572 type: integer
9573 description: Percentage progress
9574 priority:
9575 type: integer
9576 description: Job priority (less has more priority)
9577 updatedAt:
9578 type: string
9579 format: date-time
9580 createdAt:
9581 type: string
9582 format: date-time
9583 startedAt:
9584 type: string
9585 format: date-time
9586 finishedAt:
9587 type: string
9588 format: date-time
9589 parent:
9590 nullable: true
9591 description: If job has a parent job
9592 type: object
9593 properties:
9594 type:
9595 $ref: '#/components/schemas/RunnerJobType'
9596 state:
9597 $ref: '#/components/schemas/RunnerJobStateConstant'
9598 uuid:
9599 $ref: '#/components/schemas/UUIDv4'
9600 runner:
9601 nullable: true
9602 description: If job is associated to a runner
9603 properties:
9604 id:
9605 type: number
9606 name:
9607 type: string
9608 description:
9609 type: string
9610
9611 RunnerJobAdmin:
9612 allOf:
9613 - $ref: '#/components/schemas/RunnerJob'
9614 - type: object
9615 properties:
9616 privatePayload:
9617 type: object
9618
9619 callbacks:
9620 searchIndex:
9621 'https://search.example.org/api/v1/search/videos':
9622 post:
9623 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
9624 responses:
9625 '200':
9626 description: successful operation
9627 content:
9628 application/json:
9629 schema:
9630 $ref: '#/components/schemas/VideoListResponse'
ActivityPub-federated video streaming platform using P2P directly in your web browser