From 84f6e32c7be4098c08e8735825ce1bcb44e43193 Mon Sep 17 00:00:00 2001 From: Rigel Kent Date: Fri, 26 Jun 2020 13:43:27 +0200 Subject: [PATCH] add examples and descriptions, missing filters for abuses in openapi spec --- support/doc/api/openapi.yaml | 760 ++++++++++++++++++++++++++--------- 1 file changed, 565 insertions(+), 195 deletions(-) diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 82b8191b2..6c1ffee4f 100644 --- a/support/doc/api/openapi.yaml +++ b/support/doc/api/openapi.yaml @@ -31,6 +31,11 @@ info: sessions, and authenticate using this session token. One session token can currently be used at a time. + ## Roles + + Accounts are given permissions based on their role. There are three roles on + PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/#/admin-managing-users?id=roles) for a detail of their permissions. + # Errors The API uses standard HTTP status codes to indicate the success or failure @@ -48,9 +53,29 @@ externalDocs: tags: - name: Accounts description: > - Using some features of PeerTube require authentication, for which Accounts + Accounts encompass remote accounts discovered across the federation, + and correspond to the main Actor, along with video channels a user can create, which + are also Actors. + + When a comment is posted, it is done with your Account's Actor. + - name: Users + description: > + Using some features of PeerTube require authentication, for which User provide different levels of permission as well as associated user - information. Accounts also encompass remote accounts discovered across the federation. + information. Each user has a corresponding local Account for federation. + - name: My User + description: > + Operations related to your own User, when logged-in. + - name: My Subscriptions + description: > + Operations related to your subscriptions to video channels, their + new videos, and how to keep up to date with their latest publications! + - name: My Notifications + description: > + Notifications following new videos, follows or reports. They allow you + to keep track of the interactions and overall important information that + concerns you. You MAY set per-notification type delivery preference, to + receive the info either by mail, by in-browser notification or both. - name: Config description: > Each server exposes public information regarding supported videos and @@ -66,15 +91,21 @@ tags: server then deals with inter-server ActivityPub operations and propagates information across its social graph by posting activities to actors' inbox endpoints. + externalDocs: + url: https://docs.joinpeertube.org/#/admin-following-instances?id=instances-follows - name: Instance Redundancy description: > Redundancy is part of the inter-server solidarity that PeerTube fosters. Manage the list of instances you wish to help by seeding their videos according to the policy of video selection of your choice. Note that you have a similar functionality to mirror individual videos, see `Video Mirroring`. + externalDocs: + url: https://docs.joinpeertube.org/#/admin-following-instances?id=instances-redundancy - name: Plugins description: > - Managign plugins installed from a local path or from NPM. + Managing plugins installed from a local path or from NPM, or search for new ones. + externalDocs: + url: https://docs.joinpeertube.org/#/api-plugins - name: Video Abuses description: | Video abuses deal with reports of local or remote videos alike. @@ -292,6 +323,12 @@ paths: responses: '200': description: successful operation + '400': + x-summary: field inconsistencies + description: > + Arises when: + - the emailer is disabled and the instance is open to registrations + - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled delete: summary: Delete instance runtime configuration tags: @@ -332,9 +369,16 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/Job' + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + maxItems: 100 + items: + $ref: '#/components/schemas/Job' '/server/following/{host}': delete: security: @@ -350,6 +394,7 @@ paths: description: 'The host to unfollow ' schema: type: string + format: hostname responses: '201': description: successful operation @@ -428,6 +473,7 @@ paths: type: array items: type: string + format: hostname uniqueItems: true /users: post: @@ -968,6 +1014,9 @@ paths: type: array items: type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/videos/categories /videos/licences: get: summary: List available video licences @@ -982,6 +1031,9 @@ paths: type: array items: type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/videos/licences /videos/languages: get: summary: List available video languages @@ -996,6 +1048,9 @@ paths: type: array items: type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/videos/languages /videos/privacies: get: summary: List available video privacies @@ -1010,6 +1065,9 @@ paths: type: array items: type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/videos/privacies '/videos/{id}': put: summary: Update a video @@ -1038,10 +1096,12 @@ paths: format: binary category: description: Video category - type: string + type: integer + example: 4 licence: description: Video licence - type: string + type: integer + example: 2 language: description: Video language type: string @@ -1058,7 +1118,7 @@ paths: type: string nsfw: description: Whether or not this video contains sensitive content - type: string + type: boolean name: description: Video name type: string @@ -1073,7 +1133,7 @@ paths: maxLength: 30 commentsEnabled: description: Enable or disable comments for this video - type: string + type: boolean originallyPublishedAt: description: Date when the content was originally published type: string @@ -1166,11 +1226,11 @@ paths: schema: $ref: '#/components/schemas/VideoUploadResponse' '403': - description: 'The user video quota is exceeded with this video.' + description: user video quota is exceeded with this video '408': - description: 'Upload has timed out' + description: upload has timed out '422': - description: 'Invalid input file.' + description: invalid input file requestBody: content: multipart/form-data: @@ -1196,13 +1256,15 @@ paths: $ref: '#/components/schemas/VideoPrivacySet' category: description: Video category - type: string + type: integer + example: 4 licence: description: Video licence type: string language: description: Video language - type: string + type: integer + example: 2 description: description: Video description type: string @@ -1214,7 +1276,7 @@ paths: type: string nsfw: description: Whether or not this video contains sensitive content - type: string + type: boolean name: description: Video name type: string @@ -1230,7 +1292,7 @@ paths: maxLength: 30 commentsEnabled: description: Enable or disable comments for this video - type: string + type: boolean originallyPublishedAt: description: Date when the content was originally published type: string @@ -1380,6 +1442,59 @@ paths: tags: - Video Abuses parameters: + - name: id + in: query + description: only list the report with this id + schema: + type: integer + - name: predefinedReason + in: query + description: predefined reason the listed reports should contain + schema: + type: string + enum: + - violentOrAbusive + - hatefulOrAbusive + - spamOrMisleading + - privacy + - rights + - serverRules + - thumbnails + - captions + - name: search + in: query + description: plain search that will match with video titles, reporter names and more + schema: + type: string + - name: state + in: query + description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)' + schema: + type: integer + enum: + - 1 + - 2 + - 3 + - name: searchReporter + in: query + description: only list reports of a specific reporter + schema: + type: string + - name: searchReportee + description: only list reports of a specific reportee + in: query + schema: + type: string + - name: searchVideo + in: query + description: only list reports of a specific video + schema: + type: string + - name: searchVideoChannel + in: query + description: only list reports of a specific video channel + schema: + type: string - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/abusesSort' @@ -1412,6 +1527,7 @@ paths: reason: description: Reason why the user reports this video type: string + minLength: 4 predefinedReasons: description: Reason categories that help triage reports type: array @@ -1429,14 +1545,18 @@ paths: startAt: type: integer description: Timestamp in the video that marks the beginning of the report + minimum: 0 endAt: type: integer description: Timestamp in the video that marks the ending of the report + minimum: 0 required: - reason responses: '204': description: successful operation + '400': + description: incorrect request parameters '/videos/{id}/abuse/{abuseId}': put: summary: Update an abuse @@ -1446,11 +1566,6 @@ paths: - moderator tags: - Video Abuses - responses: - '204': - description: successful operation - '404': - description: video abuse not found parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/abuseId' @@ -1464,23 +1579,28 @@ paths: $ref: '#/components/schemas/VideoAbuseStateSet' moderationComment: type: string - description: 'Update the comment of the video abuse for other admin/moderators' + description: Update the report comment visible only to the moderation team + responses: + '204': + description: successful operation + '404': + description: video abuse not found delete: + tags: + - Video Abuses summary: Delete an abuse security: - OAuth2: - admin - moderator - tags: - - Video Abuses + parameters: + - $ref: '#/components/parameters/idOrUUID' + - $ref: '#/components/parameters/abuseId' responses: '204': description: successful operation '404': description: block not found - parameters: - - $ref: '#/components/parameters/idOrUUID' - - $ref: '#/components/parameters/abuseId' '/videos/{id}/blacklist': post: @@ -1521,6 +1641,24 @@ paths: - admin - moderator parameters: + - name: type + in: query + description: > + list only blocks that match this type: + + - `1`: manual block + + - `2`: automatic block that needs review + schema: + type: integer + enum: + - 1 + - 2 + - name: search + in: query + description: plain search that will match with video titles, and more + schema: + type: string - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/blacklistsSort' @@ -1530,9 +1668,15 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/VideoBlacklist' + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/VideoBlacklist' /videos/{id}/captions: get: summary: List captions of a video @@ -1550,6 +1694,7 @@ paths: properties: total: type: integer + example: 1 data: type: array items: @@ -1607,9 +1752,15 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/VideoChannel' + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/VideoChannel' post: summary: Create a video channel security: @@ -1706,6 +1857,9 @@ paths: type: array items: type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies /video-playlists: get: @@ -1722,9 +1876,15 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/VideoPlaylist' + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/VideoPlaylist' post: summary: Create a video playlist description: 'If the video playlist is set as public, the videoChannelId is mandatory.' @@ -2003,6 +2163,14 @@ paths: - Accounts parameters: - $ref: '#/components/parameters/name' + - name: withStats + in: query + description: include view statistics for the last 30 days (only if authentified as the account user) + schema: + type: boolean + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' responses: '200': description: successful operation @@ -2142,6 +2310,12 @@ paths: responses: '204': description: successful operation + '403': + description: cannot remove comment of another user + '404': + description: comment or video does not exist + '409': + description: comment is already deleted '/videos/{id}/rate': put: summary: Like/dislike a video @@ -2160,6 +2334,16 @@ paths: - Search summary: Search videos parameters: + - name: search + in: query + required: true + allowEmptyValue: false + description: > + String to search. If the user can make a remote URI search, and the string is an URI then the + PeerTube instance will fetch the remote object and add it to its database. Then, + you can use the REST API to fetch the complete video information and interact with it. + schema: + type: string - $ref: '#/components/parameters/categoryOneOf' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' @@ -2172,52 +2356,37 @@ paths: - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/searchTarget' - $ref: '#/components/parameters/videosSearchSort' - - name: search - in: query - required: true - description: > - String to search. If the user can make a remote URI search, and the string is an URI then the - PeerTube instance will fetch the remote object and add it to its database. Then, - you can use the REST API to fetch the complete video information and interact with it. - schema: - type: string - name: startDate in: query - required: true description: Get videos that are published after this date schema: type: string format: date-time - name: endDate in: query - required: true description: Get videos that are published before this date schema: type: string format: date-time - name: originallyPublishedStartDate in: query - required: true description: Get videos that are originally published after this date schema: type: string format: date-time - name: originallyPublishedEndDate in: query - required: true description: Get videos that are originally published before this date schema: type: string format: date-time - name: durationMin in: query - required: true description: Get videos that have this minimum duration schema: type: integer - name: durationMax in: query - required: true description: Get videos that have this maximum duration schema: type: integer @@ -2234,10 +2403,6 @@ paths: - Search summary: Search channels parameters: - - $ref: '#/components/parameters/start' - - $ref: '#/components/parameters/count' - - $ref: '#/components/parameters/searchTarget' - - $ref: '#/components/parameters/sort' - name: search in: query required: true @@ -2247,6 +2412,10 @@ paths: you can use the REST API to fetch the complete channel information and interact with it. schema: type: string + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/searchTarget' + - $ref: '#/components/parameters/sort' responses: '200': description: successful operation @@ -2286,6 +2455,7 @@ paths: properties: accountName: type: string + example: chocobozzz@example.org description: account to block, in the form `username@domain` required: - accountName @@ -2342,11 +2512,12 @@ paths: schema: type: object properties: - accountName: + host: type: string + format: hostname description: server domain to block required: - - accountName + - host responses: '200': description: successful operation @@ -2367,6 +2538,7 @@ paths: description: server domain to unblock schema: type: string + format: hostname responses: '201': description: successful operation @@ -2387,6 +2559,7 @@ paths: description: server domain to mirror schema: type: string + format: hostname requestBody: content: application/json: @@ -2447,7 +2620,7 @@ paths: type: object properties: videoId: - type: string + type: integer required: - videoId responses: @@ -2584,6 +2757,9 @@ paths: description: 'limit listing to a specific video channel' schema: type: string + - $ref: '#/components/parameters/sort' + - $ref: '#/components/parameters/nsfw' + - $ref: '#/components/parameters/filter' responses: '204': description: successful operation @@ -2596,6 +2772,9 @@ paths: application/xml: schema: $ref: '#/components/schemas/VideosForXML' + examples: + nightly: + externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local application/rss+xml: schema: $ref: '#/components/schemas/VideosForXML' @@ -2687,6 +2866,7 @@ paths: properties: npmName: type: string + example: peertube-plugin-auth-ldap required: - npmName additionalProperties: false @@ -2719,6 +2899,7 @@ paths: properties: npmName: type: string + example: peertube-plugin-auth-ldap required: - npmName additionalProperties: false @@ -2752,6 +2933,8 @@ paths: properties: npmName: type: string + description: name of the plugin/theme in its package.json + example: peertube-plugin-auth-ldap required: - npmName responses: @@ -2768,11 +2951,7 @@ paths: - OAuth2: - admin parameters: - - name: npmName - in: path - required: true - schema: - type: string + - $ref: '#/components/parameters/npmName' responses: '200': description: successful operation @@ -2791,11 +2970,7 @@ paths: - OAuth2: - admin parameters: - - name: npmName - in: path - required: true - schema: - type: string + - $ref: '#/components/parameters/npmName' requestBody: content: application/json: @@ -2816,11 +2991,7 @@ paths: - Plugins summary: Get a plugin's public settings parameters: - - name: npmName - in: path - required: true - schema: - type: string + - $ref: '#/components/parameters/npmName' responses: '200': description: successful operation @@ -2840,11 +3011,7 @@ paths: - OAuth2: - admin parameters: - - name: npmName - in: path - required: true - schema: - type: string + - $ref: '#/components/parameters/npmName' responses: '200': description: successful operation @@ -2871,6 +3038,7 @@ components: description: Offset used to paginate results schema: type: integer + minimum: 0 count: name: count in: query @@ -2878,15 +3046,17 @@ components: description: "Number of items to return" schema: type: integer + default: 15 maximum: 100 minimum: 1 sort: name: sort in: query required: false - description: Sort column (`-createdAt` for example) + description: Sort column schema: type: string + example: -createdAt searchTarget: name: searchTarget in: query @@ -2896,11 +3066,11 @@ components: **Warning**: If you choose to make an index search, PeerTube will get results from a third party service. - It means the instance may not know the objects you fetched. If you want to load video/channel information: + It means the instance may not yet know the objects you fetched. If you want to load video/channel information: * If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it - * If the current user has not the ability to make a remote URI search, then redirect the user on the origin instance or fetch + * 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 the data from the origin instance API schema: type: string @@ -2998,11 +3168,10 @@ components: name: name in: path required: true - description: >- - The name of the account (`chocobozzz` or `chocobozzz@example.org` for - example) + description: The name of the account schema: type: string + example: chocobozzz | chocobozzz@example.org id: name: id in: path @@ -3010,13 +3179,21 @@ components: description: The user id schema: type: integer + minimum: 0 + example: 42 idOrUUID: name: id in: path required: true description: The object id or uuid schema: - type: string + oneOf: + - type: integer + minimum: 0 + example: 42 + - type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d playlistElementId: name: playlistElementId in: path @@ -3042,16 +3219,18 @@ components: name: channelHandle in: path required: true - description: "The video channel handle (example: 'my_username@example.com' or 'my_username')" + description: The video channel handle schema: type: string + example: my_username | my_username@example.com subscriptionHandle: name: subscriptionHandle in: path required: true - description: "The subscription handle (example: 'my_username@example.com' or 'my_username')" + description: The subscription handle schema: type: string + example: my_username | my_username@example.com threadId: name: threadId in: path @@ -3070,7 +3249,7 @@ components: name: categoryOneOf in: query required: false - description: category id of the video (see /videos/categories) + description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get)) schema: oneOf: - type: integer @@ -3109,7 +3288,7 @@ components: name: languageOneOf in: query required: false - description: language id of the video (see /videos/languages). Use `_unknown` to filter on videos that don't have a video language + description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get)). Use `_unknown` to filter on videos that don't have a video language schema: oneOf: - type: string @@ -3122,7 +3301,7 @@ components: name: licenceOneOf in: query required: false - description: licence id of the video (see /videos/licences) + description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get)) schema: oneOf: - type: integer @@ -3174,6 +3353,15 @@ components: type: array items: type: string + format: uri + npmName: + name: npmName + in: path + required: true + description: name of the plugin/theme on npmjs.com or in its package.json + schema: + type: string + example: peertube-plugin-auth-ldap securitySchemes: OAuth2: description: > @@ -3306,14 +3494,17 @@ components: - serverRules - thumbnails - captions + example: [spamOrMisleading] VideoResolutionConstant: properties: id: type: integer description: 'Video resolution (240, 360, 720 ...)' + example: 240 label: type: string + example: 240p VideoScheduledUpdate: properties: privacy: @@ -3334,8 +3525,10 @@ components: type: string url: type: string + format: url host: type: string + format: hostname avatar: nullable: true allOf: @@ -3350,8 +3543,10 @@ components: type: string url: type: string + format: url host: type: string + format: hostname avatar: nullable: true allOf: @@ -3379,16 +3574,21 @@ components: description: 'Video file size in bytes' torrentUrl: type: string + format: url torrentDownloadUrl: type: string + format: url fileUrl: type: string + format: url fileDownloadUrl: type: string + format: url fps: type: number metadataUrl: type: string + format: url VideoStreamingPlaylists: properties: id: @@ -3400,8 +3600,10 @@ components: description: 'Playlist type (HLS = `1`)' playlistUrl: type: string + format: url segmentsSha256Url: type: string + format: url files: type: array items: @@ -3413,28 +3615,38 @@ components: properties: baseUrl: type: string + format: url VideoInfo: properties: id: type: integer uuid: type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d name: type: string Video: properties: id: type: integer + example: 8 uuid: type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d createdAt: type: string + format: date-time publishedAt: type: string + format: date-time updatedAt: type: string + format: date-time originallyPublishedAt: type: string + format: date-time category: $ref: '#/components/schemas/VideoConstantNumber' licence: @@ -3447,22 +3659,30 @@ components: type: string duration: type: integer + example: 1419 isLocal: type: boolean name: type: string + example: What is PeerTube? thumbnailPath: type: string + example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg previewPath: type: string + example: /static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg embedPath: type: string + example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee views: type: integer + example: 1337 likes: type: integer + example: 42 dislikes: type: integer + example: 7 nsfw: type: boolean waitTranscoding: @@ -3499,6 +3719,7 @@ components: type: string support: type: string + example: Please support my work on ! <3 channel: $ref: '#/components/schemas/VideoChannel' account: @@ -3507,6 +3728,7 @@ components: type: array items: type: string + example: [flowers, gardening] files: type: array items: @@ -3519,6 +3741,7 @@ components: type: array items: type: string + format: url streamingPlaylists: type: array items: @@ -3529,8 +3752,14 @@ components: type: integer fileUrl: type: string + format: url strategy: type: string + enum: + - manual + - most-views + - trending + - recently-added size: type: integer createdAt: @@ -3550,8 +3779,11 @@ components: type: string url: type: string + format: url uuid: type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d redundancies: type: object properties: @@ -3574,37 +3806,42 @@ components: description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)' label: type: string + example: Pending VideoImport: properties: id: type: integer + example: 2 targetUrl: type: string + format: url + example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d magnetUri: type: string + format: uri + example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4 torrentName: type: string state: - type: object - properties: - id: - $ref: '#/components/schemas/VideoImportStateConstant' - label: - type: string + $ref: '#/components/schemas/VideoImportStateConstant' error: type: string createdAt: type: string + format: date-time updatedAt: type: string + format: date-time video: $ref: '#/components/schemas/Video' VideoAbuse: properties: id: type: integer + example: 7 reason: type: string + example: The video is a spam predefinedReasons: $ref: '#/components/schemas/VideoAbusePredefinedReasons' reporterAccount: @@ -3613,6 +3850,7 @@ components: $ref: '#/components/schemas/VideoAbuseStateConstant' moderationComment: type: string + example: Decided to ban the server since it spams us regularly video: type: object properties: @@ -3622,8 +3860,11 @@ components: type: string uuid: type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d createdAt: type: string + format: date-time VideoBlacklist: properties: id: @@ -3632,12 +3873,16 @@ components: type: integer createdAt: type: string + format: date-time updatedAt: type: string + format: date-time name: type: string uuid: type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d description: type: string duration: @@ -3665,18 +3910,24 @@ components: type: integer uuid: type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d VideoPlaylist: properties: id: type: integer createdAt: type: string + format: date-time updatedAt: type: string + format: date-time description: type: string uuid: type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d displayName: type: string isLocal: @@ -3699,6 +3950,7 @@ components: type: integer url: type: string + format: url text: type: string threadId: @@ -3709,8 +3961,10 @@ components: type: integer createdAt: type: string + format: date-time updatedAt: type: string + format: date-time totalRepliesFromVideoAuthor: type: integer totalReplies: @@ -3737,18 +3991,22 @@ components: type: string createdAt: type: string + format: date-time updatedAt: type: string + format: date-time ActorInfo: properties: id: type: integer + example: 11 name: type: string displayName: type: string host: type: string + format: hostname avatar: nullable: true type: object @@ -3759,20 +4017,25 @@ components: properties: id: type: integer + example: 11 url: type: string + format: url name: type: string host: type: string + format: hostname followingCount: type: integer followersCount: type: integer createdAt: type: string + format: date-time updatedAt: type: string + format: date-time avatar: $ref: '#/components/schemas/Avatar' Account: @@ -3781,73 +4044,17 @@ components: - properties: userId: type: string + example: 2 displayName: type: string description: type: string - User: - properties: - id: - type: integer - username: - type: string - email: - type: string - theme: - type: string - description: 'Theme enabled by this user' - emailVerified: - type: boolean - description: 'Has the user confirmed their email address?' - nsfwPolicy: - $ref: '#/components/schemas/NSFWPolicy' - webtorrentEnabled: - type: boolean - autoPlayVideo: - type: boolean - description: 'Automatically start playing the video on the watch page' - role: - $ref: '#/components/schemas/UserRole' - roleLabel: - type: string - enum: - - User - - Moderator - - Administrator - videoQuota: - type: integer - videoQuotaDaily: - type: integer - videosCount: - type: integer - videoAbusesCount: - type: integer - videoAbusesAcceptedCount: - type: integer - videoAbusesCreatedCount: - type: integer - videoCommentsCount: - type: integer - noInstanceConfigWarningModal: - type: boolean - noWelcomeModal: - type: boolean - blocked: - type: boolean - blockedReason: - type: string - createdAt: - type: string - account: - $ref: '#/components/schemas/Account' - videoChannels: - type: array - items: - $ref: '#/components/schemas/VideoChannel' UserWatchingVideo: properties: currentTime: type: integer + description: timestamp within the video, in seconds + example: 5 ServerConfig: properties: instance: @@ -4044,6 +4251,7 @@ components: properties: indexUrl: type: string + format: url ServerConfigAbout: properties: instance: @@ -4125,6 +4333,7 @@ components: properties: email: type: string + format: email contactForm: type: object properties: @@ -4223,38 +4432,61 @@ components: - accepted createdAt: type: string + format: date-time updatedAt: type: string + format: date-time Job: properties: id: type: integer + minimum: 0 + example: 42 state: type: string enum: - - pending - - processing - - error - - success - category: + - active + - completed + - failed + - waiting + - delayed + type: type: string enum: - - transcoding - - activitypub-http - handlerName: - type: string - handlerInputData: - type: string + - activitypub-http-unicast + - activitypub-http-broadcast + - activitypub-http-fetcher + - activitypub-follow + - video-file-import + - video-transcoding + - email + - video-import + - videos-views + - activitypub-refresher + - video-redundancy + data: + type: object + additionalProperties: true + error: + type: object + additionalProperties: true createdAt: type: string - updatedAt: + format: date-time + finishedOn: type: string + format: date-time + processedOn: + type: string + format: date-time AddUserResponse: properties: id: type: integer uuid: type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d VideoUploadResponse: properties: video: @@ -4262,14 +4494,19 @@ components: properties: id: type: integer + example: 8 uuid: type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d CommentThreadResponse: properties: total: type: integer + example: 1 data: type: array + maxItems: 100 items: $ref: '#/components/schemas/VideoComment' CommentThreadPostResponse: @@ -4280,31 +4517,103 @@ components: properties: total: type: integer + example: 1 data: type: array + maxItems: 100 items: $ref: '#/components/schemas/Video' + User: + properties: + id: + type: integer + readOnly: true + username: + type: string + description: The user username + minLength: 1 + maxLength: 50 + email: + type: string + format: email + description: The user email + theme: + type: string + description: Theme enabled by this user + emailVerified: + type: boolean + description: Has the user confirmed their email address? + nsfwPolicy: + $ref: '#/components/schemas/NSFWPolicy' + webtorrentEnabled: + type: boolean + description: Enable P2P in the player + autoPlayVideo: + type: boolean + description: Automatically start playing the video on the watch page + role: + $ref: '#/components/schemas/UserRole' + roleLabel: + type: string + enum: + - User + - Moderator + - Administrator + videoQuota: + type: integer + description: The user video quota + videoQuotaDaily: + type: integer + description: The user daily video quota + videosCount: + type: integer + videoAbusesCount: + type: integer + videoAbusesAcceptedCount: + type: integer + videoAbusesCreatedCount: + type: integer + videoCommentsCount: + type: integer + noInstanceConfigWarningModal: + type: boolean + noWelcomeModal: + type: boolean + blocked: + type: boolean + blockedReason: + type: string + createdAt: + type: string + account: + $ref: '#/components/schemas/Account' + videoChannels: + type: array + items: + $ref: '#/components/schemas/VideoChannel' AddUser: properties: username: type: string - description: 'The user username' + description: The user username minLength: 1 maxLength: 50 password: type: string - description: 'The user password. If the smtp server is configured, you can leave empty and an email will be sent' + format: password + description: The user password. If the smtp server is configured, you can leave empty and an email will be sent minLength: 6 maxLength: 255 email: type: string - description: 'The user email. MUST be in the format of an email address.' + format: email + description: The user email videoQuota: - type: string - description: 'The user video quota' + type: integer + description: The user video quota videoQuotaDaily: - type: string - description: 'The user daily video quota' + type: integer + description: The user daily video quota role: $ref: '#/components/schemas/UserRole' required: @@ -4318,16 +4627,17 @@ components: properties: id: type: string - description: 'The user id' + description: The user id email: type: string - description: 'The updated email of the user' + format: email + description: The updated email of the user videoQuota: - type: string - description: 'The updated video quota of the user' + type: integer + description: The updated video quota of the user videoQuotaDaily: - type: string - description: 'The updated daily video quota of the user' + type: integer + description: The updated daily video quota of the user role: $ref: '#/components/schemas/UserRole' required: @@ -4340,16 +4650,24 @@ components: properties: password: type: string - description: 'Your new password' + format: password + description: Your new password + minLength: 6 + maxLength: 255 email: type: string - description: 'Your new email' + format: email + description: Your new email displayNSFW: type: string - description: 'Your new displayNSFW' + description: Your new displayNSFW + enum: + - 'true' + - 'false' + - both autoPlayVideo: - type: string - description: 'Your new autoPlayVideo' + type: boolean + description: Your new autoPlayVideo required: - password - email @@ -4359,10 +4677,10 @@ components: properties: id: type: string - description: 'Id of the video' + description: Id of the video rating: type: number - description: 'Rating of the video' + description: Rating of the video required: - id - rating @@ -4380,26 +4698,37 @@ components: properties: username: type: string - description: 'The username of the user' + description: The username of the user + minLength: 1 + maxLength: 50 + pattern: '/^[a-z0-9._]{1,50}$/' password: type: string - description: 'The password of the user' + format: password + description: The password of the user + minLength: 6 + maxLength: 255 email: type: string - description: 'The email of the user' + format: email + description: The email of the user displayName: type: string - description: 'The user display name' + description: The user display name + minLength: 1 + maxLength: 120 channel: type: object properties: name: type: string - description: 'The name for the default channel' + description: The name for the default channel + pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/' displayName: type: string - description: 'The display name for the default channel' - + description: The display name for the default channel + minLength: 1 + maxLength: 120 required: - username - password @@ -4453,6 +4782,7 @@ components: properties: url: type: string + format: url xml: attribute: true fileSize: @@ -4491,6 +4821,7 @@ components: properties: link: type: string + format: url guid: type: string pubDate: @@ -4512,6 +4843,7 @@ components: properties: link: type: string + format: url description: video watch page URL guid: type: string @@ -4548,6 +4880,7 @@ components: properties: url: type: string + format: url description: video embed path, relative to the canonical URL domain (MRSS) xml: attribute: true @@ -4556,6 +4889,7 @@ components: properties: url: type: string + format: url description: video watch path, relative to the canonical URL domain (MRSS) xml: attribute: true @@ -4564,6 +4898,7 @@ components: properties: url: type: string + format: url xml: attribute: true height: @@ -4591,6 +4926,7 @@ components: properties: url: type: string + format: url xml: attribute: true type: @@ -4614,8 +4950,11 @@ components: type: integer description: > Notification type + - `0` NONE + - `1` WEB + - `2` EMAIL enum: - 0 @@ -4629,19 +4968,33 @@ components: type: integer description: > Notification type, following the `UserNotificationType` enum: + - `1` NEW_VIDEO_FROM_SUBSCRIPTION + - `2` NEW_COMMENT_ON_MY_VIDEO + - `3` NEW_VIDEO_ABUSE_FOR_MODERATORS + - `4` BLACKLIST_ON_MY_VIDEO + - `5` UNBLACKLIST_ON_MY_VIDEO + - `6` MY_VIDEO_PUBLISHED + - `7` MY_VIDEO_IMPORT_SUCCESS + - `8` MY_VIDEO_IMPORT_ERROR + - `9` NEW_USER_REGISTRATION + - `10` NEW_FOLLOW + - `11` COMMENT_MENTION + - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS + - `13` NEW_INSTANCE_FOLLOWER + - `14` AUTO_INSTANCE_FOLLOWING read: type: boolean @@ -4667,9 +5020,11 @@ components: nullable: true magnetUri: type: string + format: uri nullable: true targetUri: type: string + format: uri nullable: true comment: nullable: true @@ -4733,6 +5088,7 @@ components: type: string host: type: string + format: hostname createdAt: type: string format: date-time @@ -4743,33 +5099,45 @@ components: properties: total: type: integer + example: 1 data: type: array + maxItems: 100 items: $ref: '#/components/schemas/Notification' Plugin: properties: name: type: string + example: peertube-plugin-auth-ldap type: type: integer + description: > + - `1`: PLUGIN + + - `2`: THEME enum: - 1 - 2 latestVersion: type: string + example: 0.0.3 version: type: string + example: 0.0.1 enabled: type: boolean uninstalled: type: boolean peertubeEngine: type: string + example: 2.2.0 description: type: string homepage: type: string + format: url + example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap settings: type: object additionalProperties: true @@ -4783,7 +5151,9 @@ components: properties: total: type: integer + example: 1 data: type: array + maxItems: 100 items: $ref: '#/components/schemas/Plugin' \ No newline at end of file -- 2.25.1