ニジカ投稿局 https://tv.nizika.tv
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

11224 lines
324 KiB

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