X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=2fb154dbdbe6c7e4384d947ca0f7c897da504121;hb=a69ea13086273fc6659c153be93f0f5b37aad733;hp=123e54f47ca549865ba2f8234a154d9b286a84d2;hpb=961cbe4269e5f34639e29310fb3d90a6cb1bd6bc;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 123e54f47..2fb154dbd 100644 --- a/support/doc/api/openapi.yaml +++ b/support/doc/api/openapi.yaml @@ -145,7 +145,6 @@ info: | `/api/*` | | `/download/*` | | `/lazy-static/*` | - | `/live/segments-sha256/*` | | `/.well-known/webfinger` | In addition, all routes serving ActivityPub are CORS-enabled for all origins. @@ -247,13 +246,15 @@ tags: ### Import - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/) - - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file - - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file + - _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file + - _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file The import function is practical when the desired video/audio is available online. It makes PeerTube download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have. - name: Video Imports description: Operations dealing with listing, adding and removing video imports. + - name: Channels Sync + description: Operations dealing with synchronizing PeerTube user's channel with channels of other platforms - name: Video Captions description: Operations dealing with listing, adding and removing closed captions of a video. - name: Video Channels @@ -293,6 +294,10 @@ tags: PeerTube instances can mirror videos from one another, and help distribute some videos. For importing videos as your own, refer to [video imports](#operation/importVideo). + - name: Stats + description: | + Statistics + x-tagGroups: - name: Auth tags: @@ -323,26 +328,25 @@ x-tagGroups: - Video Transcoding - Live Videos - Feeds + - Channels Sync - name: Search tags: - Search - - name: Custom pages - tags: - - Homepage - name: Moderation tags: - Abuses - Video Blocks - Account Blocks - Server Blocks - - name: Instance Configuration + - name: Instance tags: - Config + - Homepage - Instance Follows - Instance Redundancy - Plugins - - name: Jobs - tags: + - Stats + - Logs - Job paths: '/accounts/{name}': @@ -1122,6 +1126,97 @@ paths: '404': description: user not found + /users/{id}/two-factor/request: + post: + summary: Request two factor auth + operationId: requestTwoFactor + description: Request two factor authentication for a user + tags: + - Users + parameters: + - $ref: '#/components/parameters/id' + requestBody: + content: + application/json: + schema: + type: object + properties: + currentPassword: + type: string + description: Password of the currently authenticated user + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/RequestTwoFactorResponse' + '403': + description: invalid password + '404': + description: user not found + + /users/{id}/two-factor/confirm-request: + post: + summary: Confirm two factor auth + operationId: confirmTwoFactorRequest + description: Confirm a two factor authentication request + tags: + - Users + parameters: + - $ref: '#/components/parameters/id' + requestBody: + content: + application/json: + schema: + type: object + properties: + requestToken: + type: string + description: Token to identify the two factor request + otpToken: + type: string + description: OTP token generated by the app + required: + - requestToken + - otpToken + responses: + '204': + description: successful operation + '403': + description: invalid request token or OTP token + '404': + description: user not found + + /users/{id}/two-factor/disable: + post: + summary: Disable two factor auth + operationId: disableTwoFactor + description: Disable two factor authentication of a user + tags: + - Users + parameters: + - $ref: '#/components/parameters/id' + requestBody: + content: + application/json: + schema: + type: object + properties: + currentPassword: + type: string + description: Password of the currently authenticated user + responses: + '204': + description: successful operation + '403': + description: invalid password + '404': + description: user not found + + /users/ask-send-verify-email: post: summary: Resend user verification link @@ -1182,6 +1277,27 @@ paths: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' + - + name: targetUrl + in: query + required: false + description: Filter on import target URL + schema: + type: string + - + name: videoChannelSyncId + in: query + required: false + description: Filter on imports created by a specific channel synchronization + schema: + type: number + - + name: search + in: query + required: false + description: Search in video names + schema: + type: string responses: '200': description: successful operation @@ -1669,6 +1785,31 @@ paths: '404': description: video not found + /videos/{id}/studio/edit: + post: + summary: Create a studio task + tags: + - Video Transcoding + - Video + description: Create a task to edit a video (cut, add intro/outro etc) + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/VideoStudioCreateTask' + responses: + '204': + description: successful operation + '400': + description: incorrect parameters + '404': + description: video not found + /videos: get: summary: List videos @@ -1903,6 +2044,22 @@ paths: example: | **[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)** + '/videos/{id}/source': + post: + summary: Get video source file metadata + operationId: getVideoSource + tags: + - Video + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoSource' + '/videos/{id}/views': post: summary: Notify user is watching a video @@ -1952,6 +2109,18 @@ paths: - OAuth2: [] parameters: - $ref: '#/components/parameters/idOrUUID' + - name: startDate + in: query + description: Filter stats by start date + schema: + type: string + format: date-time + - name: endDate + in: query + description: Filter stats by end date + schema: + type: string + format: date-time responses: '200': description: successful operation @@ -1996,6 +2165,18 @@ paths: enum: - 'viewers' - 'aggregateWatchTime' + - name: startDate + in: query + description: Filter stats by start date + schema: + type: string + format: date-time + - name: endDate + in: query + description: Filter stats by end date + schema: + type: string + format: date-time responses: '200': description: successful operation @@ -2029,7 +2210,7 @@ paths: x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy description: | If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`: - - `quota_reached` for quota limits wether daily or global + - `quota_reached` for quota limits whether daily or global headers: X-File-Maximum-Size: schema: @@ -2462,6 +2643,48 @@ paths: description: bad parameters or trying to update a live that has already started '403': description: trying to save replay of the live but saving replay is not enabled on the instance + /videos/live/{id}/sessions: + get: + summary: List live sessions + description: List all sessions created in a particular live + security: + - OAuth2: [] + tags: + - Live Videos + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/LiveVideoSessionResponse' + /videos/{id}/live-session: + get: + summary: Get live session of a replay + description: If the video is a replay of a live, you can find the associated live session using this endpoint + security: + - OAuth2: [] + tags: + - Live Videos + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/LiveVideoSessionResponse' /users/me/abuses: get: @@ -2941,7 +3164,7 @@ paths: tags: - Video Channels responses: - '204': + '200': description: successful operation content: application/json: @@ -3179,6 +3402,79 @@ paths: '204': description: successful operation + '/video-channels/{channelHandle}/import-videos': + post: + summary: Import videos in channel + description: Import a remote channel/playlist videos into a channel + security: + - OAuth2: [] + tags: + - Video Channels + - Channels Sync + parameters: + - $ref: '#/components/parameters/channelHandle' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ImportVideosInChannelCreate' + responses: + '204': + description: successful operation + + '/video-channel-syncs': + post: + summary: Create a synchronization for a video channel + operationId: addVideoChannelSync + security: + - OAuth2: [] + tags: + - Channels Sync + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/VideoChannelSyncCreate' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + videoChannelSync: + $ref: "#/components/schemas/VideoChannelSync" + + '/video-channel-syncs/{channelSyncId}': + delete: + summary: Delete a video channel synchronization + operationId: delVideoChannelSync + security: + - OAuth2: [] + tags: + - Channels Sync + parameters: + - $ref: '#/components/parameters/channelSyncId' + responses: + '204': + description: successful operation + + '/video-channel-syncs/{channelSyncId}/sync': + post: + summary: Triggers the channel synchronization job, fetching all the videos from the remote channel + operationId: triggerVideoChannelSync + security: + - OAuth2: [] + tags: + - Channels Sync + parameters: + - $ref: '#/components/parameters/channelSyncId' + responses: + '204': + description: successful operation + + /video-playlists/privacies: get: summary: List available playlist privacy policies @@ -3536,7 +3832,7 @@ paths: - $ref: '#/components/parameters/name' - name: withStats in: query - description: include view statistics for the last 30 days (only if authentified as the account user) + description: include daily view statistics for the last 30 days and total views (only if authentified as the account user) schema: type: boolean - $ref: '#/components/parameters/start' @@ -3550,6 +3846,26 @@ paths: schema: $ref: '#/components/schemas/VideoChannelList' + '/accounts/{name}/video-channel-syncs': + get: + summary: List the synchronizations of video channels of an account + tags: + - Video Channels + - Channels Sync + - Accounts + parameters: + - $ref: '#/components/parameters/name' + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoChannelSyncList' + '/accounts/{name}/ratings': get: summary: List ratings of an account @@ -4212,6 +4528,74 @@ paths: '404': description: video redundancy not found + /server/stats: + get: + tags: + - Stats + summary: Get instance stats + description: Get instance public statistics. This endpoint is cached. + operationId: getInstanceStats + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/ServerStats' + + /server/logs/client: + post: + tags: + - Logs + summary: Send client log + operationId: sendClientLog + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SendClientLog' + responses: + '204': + description: successful operation + + /server/logs: + get: + tags: + - Logs + summary: Get instance logs + operationId: getInstanceLogs + security: + - OAuth2: + - admin + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: array + items: + type: string + + /server/audit-logs: + get: + tags: + - Logs + summary: Get instance audit logs + operationId: getInstanceAuditLogs + security: + - OAuth2: + - admin + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: array + items: + type: string + '/feeds/video-comments.{format}': get: tags: @@ -4715,6 +5099,21 @@ paths: '404': description: plugin not found + /metrics/playback: + post: + summary: Create playback metrics + description: These metrics are exposed by OpenTelemetry metrics exporter if enabled. + tags: + - Stats + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PlaybackMetricCreate' + responses: + '204': + description: successful operation + servers: - url: 'https://peertube2.cpy.re/api/v1' description: Live Test Server (live data - latest nightly version) @@ -4964,6 +5363,13 @@ components: schema: type: string example: my_username | my_username@example.com + channelSyncId: + name: channelSyncId + in: path + required: true + description: Channel Sync id + schema: + $ref: '#/components/schemas/Abuse/properties/id' subscriptionHandle: name: subscriptionHandle in: path @@ -5170,6 +5576,7 @@ components: - activitypub-refresher - video-redundancy - video-live-ending + - video-channel-import followState: name: state in: query @@ -5211,7 +5618,7 @@ components: moderator: Moderator scope user: User scope schemas: - # Resuable core properties + # Reusable core properties id: type: integer minimum: 1 @@ -5377,7 +5784,7 @@ components: - 1 - 2 - 3 - description: 'The live latency mode (Default = `1`, HIght latency = `2`, Small Latency = `3`)' + description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)' VideoStateConstant: properties: @@ -5513,6 +5920,8 @@ components: VideoFile: readOnly: true properties: + id: + $ref: '#/components/schemas/id' magnetUri: type: string format: uri @@ -6075,6 +6484,10 @@ components: $ref: '#/components/schemas/VideoConstantString-Language' captionPath: type: string + VideoSource: + properties: + filename: + type: string ActorImage: properties: path: @@ -6178,14 +6591,6 @@ components: viewersPeakDate: type: string format: date-time - views: - type: number - likes: - type: number - dislikes: - type: number - comments: - type: number countries: type: array items: @@ -6322,6 +6727,11 @@ components: properties: enabled: type: boolean + videoChannelSynchronization: + type: object + properties: + enabled: + type: boolean autoBlacklist: type: object properties: @@ -6425,6 +6835,96 @@ components: enabled: type: boolean + SendClientLog: + properties: + message: + type: string + url: + type: string + description: URL of the current user page + level: + enum: + - error + - warn + stackTrace: + type: string + description: Stack trace of the error if there is one + userAgent: + type: string + description: User agent of the web browser that sends the message + meta: + type: string + description: Additional information regarding this log + required: + - message + - url + - level + + ServerStats: + properties: + totalUsers: + type: number + totalDailyActiveUsers: + type: number + totalWeeklyActiveUsers: + type: number + totalMonthlyActiveUsers: + type: number + totalLocalVideos: + type: number + totalLocalVideoViews: + type: number + description: Total video views made on the instance + totalLocalVideoComments: + type: number + description: Total comments made by local users + totalLocalVideoFilesSize: + type: number + totalVideos: + type: number + totalVideoComments: + type: number + totalLocalVideoChannels: + type: number + totalLocalDailyActiveVideoChannels: + type: number + totalLocalWeeklyActiveVideoChannels: + type: number + totalLocalMonthlyActiveVideoChannels: + type: number + totalLocalPlaylists: + type: number + totalInstanceFollowers: + type: number + totalInstanceFollowing: + type: number + videosRedundancy: + type: array + items: + type: object + properties: + strategy: + type: string + totalSize: + type: number + totalUsed: + type: number + totalVideoFiles: + type: number + totalVideos: + type: number + totalActivityPubMessagesProcessed: + type: number + totalActivityPubMessagesSuccesses: + type: number + totalActivityPubMessagesErrors: + type: number + + activityPubMessagesProcessedPerSecond: + type: number + totalActivityPubMessagesWaiting: + type: number + ServerConfigAbout: properties: instance: @@ -6596,6 +7096,11 @@ components: properties: enabled: type: boolean + video_channel_synchronization: + type: object + properties: + enabled: + type: boolean autoBlacklist: type: object properties: @@ -6688,6 +7193,7 @@ components: - videos-views-stats - activitypub-refresher - video-redundancy + - video-channel-import data: type: object additionalProperties: true @@ -7208,6 +7714,7 @@ components: type: integer uuid: $ref: '#/components/schemas/UUIDv4' + VideoChannelCreate: allOf: - $ref: '#/components/schemas/VideoChannel' @@ -7238,6 +7745,63 @@ components: - $ref: '#/components/schemas/VideoChannel' - $ref: '#/components/schemas/Actor' + ImportVideosInChannelCreate: + type: object + properties: + externalChannelUrl: + type: string + example: https://youtube.com/c/UC_myfancychannel + videoChannelSyncId: + type: integer + description: If part of a channel sync process, specify its id to assign video imports to this channel synchronization + required: + - 'externalChannelUrl' + + VideoChannelSync: + type: object + properties: + id: + $ref: '#/components/schemas/id' + state: + type: object + properties: + id: + type: integer + example: 2 + label: + type: string + example: PROCESSING + externalChannelUrl: + type: string + example: 'https://youtube.com/c/UC_myfancychannel' + createdAt: + type: string + format: date-time + lastSyncAt: + type: string + format: date-time + nullable: true + channel: + $ref: '#/components/schemas/VideoChannel' + VideoChannelSyncList: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + allOf: + - $ref: '#/components/schemas/VideoChannelSync' + VideoChannelSyncCreate: + type: object + properties: + externalChannelUrl: + type: string + example: https://youtube.com/c/UC_myfancychannel + videoChannelId: + $ref: '#/components/schemas/id' MRSSPeerLink: type: object xml: @@ -7673,6 +8237,165 @@ components: description: User can select live latency mode if enabled by the instance $ref: '#/components/schemas/LiveVideoLatencyMode' + RequestTwoFactorResponse: + properties: + otpRequest: + type: object + properties: + requestToken: + type: string + description: The token to send to confirm this request + secret: + type: string + description: The OTP secret + uri: + type: string + description: The OTP URI + + VideoStudioCreateTask: + type: array + items: + anyOf: + - + title: cut + type: object + properties: + name: + type: string + enum: + - 'cut' + options: + type: object + properties: + start: + type: integer + end: + type: integer + - + title: add-intro + type: object + properties: + name: + type: string + enum: + - 'add-intro' + options: + type: object + properties: + file: + type: string + format: binary + - + title: add-outro + type: object + properties: + name: + type: string + enum: + - 'add-outro' + options: + type: object + properties: + file: + type: string + format: binary + - + title: add-watermark + type: object + properties: + name: + type: string + enum: + - 'add-watermark' + options: + type: object + properties: + file: + type: string + format: binary + + LiveVideoSessionResponse: + properties: + id: + type: integer + startDate: + type: string + format: date-time + description: Start date of the live session + endDate: + type: string + format: date-time + nullable: true + description: End date of the live session + error: + type: integer + enum: + - 1 + - 2 + - 3 + - 4 + - 5 + nullable: true + description: > + Error type if an error occurred during the live session: + - `1`: Bad socket health (transcoding is too slow) + - `2`: Max duration exceeded + - `3`: Quota exceeded + - `4`: Quota FFmpeg error + - `5`: Video has been blacklisted during the live + replayVideo: + type: object + description: Video replay information + properties: + id: + type: number + uuid: + $ref: '#/components/schemas/UUIDv4' + shortUUID: + $ref: '#/components/schemas/shortUUID' + + PlaybackMetricCreate: + properties: + playerMode: + type: string + enum: + - 'p2p-media-loader' + - 'webtorrent' + resolution: + type: number + description: Current player video resolution + fps: + type: number + description: Current player video fps + resolutionChanges: + type: number + description: How many resolution changes occured since the last metric creation + errors: + type: number + description: How many errors occured since the last metric creation + downloadedBytesP2P: + type: number + description: How many bytes were downloaded with P2P since the last metric creation + downloadedBytesHTTP: + type: number + description: How many bytes were downloaded with HTTP since the last metric creation + uploadedBytesP2P: + type: number + description: How many bytes were uploaded with P2P since the last metric creation + videoId: + oneOf: + - $ref: '#/components/schemas/id' + - $ref: '#/components/schemas/UUIDv4' + - $ref: '#/components/schemas/shortUUID' + required: + - playerMode + - resolutionChanges + - errors + - downloadedBytesP2P + - downloadedBytesHTTP + - uploadedBytesP2P + - videoId + callbacks: searchIndex: 'https://search.example.org/api/v1/search/videos':