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