cpy.re – peertube

OpenAPI apis-guru social

The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with which generates a client SDK in the language of your choice - we generate some client SDKs automatically:

See the for a few examples of using the PeerTube API.

Authentication

When you sign up for an account on a PeerTube instance, you are given the possibility to generate sessions on it, and authenticate there using an access token. Only one access 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 for a detail of their permissions.

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call, completed by a response body.

HTTP 1.1 404 Not FoundContent-Type: application/problem+json; charset=utf-8
{  "detail": "Video not found",  "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",  "status": 404,  "title": "Not Found",  "type": "about:blank"}

We provide error type values for , but it is still optional. Types are used to disambiguate errors that bear the same status code and are non-obvious:

HTTP 1.1 403 ForbiddenContent-Type: application/problem+json; charset=utf-8
{  "detail": "Cannot get this video regarding follow constraints",  "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",  "status": 403,  "title": "Forbidden",  "type": "https://docs.joinpeertube.org/api/rest-reference.html#section/Errors/does_not_respect_follow_constraints"}

Here a 403 error could otherwise mean that the video is private or blocklisted.

Validation errors

Each parameter is evaluated on its own against a set of rules before the route validator proceeds with potential testing involving parameter combinations. Errors coming from validation errors appear earlier and benefit from a more detailed error description:

HTTP 1.1 400 Bad RequestContent-Type: application/problem+json; charset=utf-8
{  "detail": "Incorrect request parameters: id",  "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",  "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",  "invalid-params": {    "id": {      "location": "params",      "msg": "Invalid value",      "param": "id",      "value": "9c9de5e8-0a1e-484a-b099-e80766180"    }  },  "status": 400,  "title": "Bad Request",  "type": "about:blank"}

Where id is the name of the field concerned by the error, within the route definition. invalid-params.<field>.location can be either 'params', 'body', 'header', 'query' or 'cookies', and invalid-params.<field>.value reports the value that didn't pass validation whose invalid-params.<field>.msg is about.

Deprecated error fields

Some fields could be included with previous versions. They are still included but their use is deprecated:

error: superseded by detail
code: superseded by type (which is now an URI)

Rate limits

We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:

Endpoint (prefix: `/api/v1`)	Calls	Time frame
`/*`	50	10 seconds
`POST /users/token`	15	5 minutes
`POST /users/register`	2^*	5 minutes
`POST /users/ask-send-verify-email`	3	5 minutes

Depending on the endpoint, ^*failed requests are not taken into account. A service limit is announced by a 429 Too Many Requests status code.

You can get details about the current state of your rate limit by reading the following headers:

Header	Description
`X-RateLimit-Limit`	Number of max requests allowed in the current time period
`X-RateLimit-Remaining`	Number of remaining requests in the current time period
`X-RateLimit-Reset`	Timestamp of end of current time period as UNIX timestamp
`Retry-After`	Seconds to delay after the first `429` is received

CORS

This API features , allowing cross-domain communication from the browser for some routes:

| Endpoint | |------------------------- ---| | /api/* | | /download/* | | /lazy-static/* | | /.well-known/webfinger |

In addition, all routes serving ActivityPub are CORS-enabled for all origins.

HTTP 1.1 404 Not FoundContent-Type: application/problem+json; charset=utf-8
{  "detail": "Video not found",  "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",  "status": 404,  "title": "Not Found",  "type": "about:blank"}

HTTP 1.1 403 ForbiddenContent-Type: application/problem+json; charset=utf-8
{  "detail": "Cannot get this video regarding follow constraints",  "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",  "status": 403,  "title": "Forbidden",  "type": "https://docs.joinpeertube.org/api/rest-reference.html#section/Errors/does_not_respect_follow_constraints"}

HTTP 1.1 400 Bad RequestContent-Type: application/problem+json; charset=utf-8
{  "detail": "Incorrect request parameters: id",  "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",  "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",  "invalid-params": {    "id": {      "location": "params",      "msg": "Invalid value",      "param": "id",      "value": "9c9de5e8-0a1e-484a-b099-e80766180"    }  },  "status": 400,  "title": "Bad Request",  "type": "about:blank"}

Homepage: https://api.apis.guru/v2/specs/cpy.re:peertube/5.1.0.json
Provider: cpy.re:peertube / peertube
OpenAPI version: 3.0.0
Spec (JSON): https://api.apis.guru/v2/specs/cpy.re/peertube/5.1.0/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/cpy.re/peertube/5.1.0/openapi.yaml

Tools (188)

Extracted live via the executor SDK.

abuses.deleteApiV1AbusesAbuseId

Delete an abuse
abuses.deleteApiV1AbusesAbuseIdMessagesAbuseMessageId

Delete an abuse message
abuses.getAbuses

List abuses
abuses.getApiV1AbusesAbuseIdMessages

List messages of an abuse
abuses.getMyAbuses

List my abuses
abuses.postApiV1Abuses

Report an abuse
abuses.postApiV1AbusesAbuseIdMessages

Add message to an abuse
abuses.putApiV1AbusesAbuseId

Update an abuse
accountBlocks.deleteApiV1ServerBlocklistAccountsAccountName

Unblock an account by its handle
accountBlocks.getApiV1BlocklistStatus

Get block status of accounts/hosts
accountBlocks.getApiV1ServerBlocklistAccounts

List account blocks
accountBlocks.postApiV1ServerBlocklistAccounts

Block an account
accounts.getAccount

Get an account
accounts.getAccountFollowers

List followers of an account
accounts.getAccounts

List accounts
accounts.getAccountVideos

List videos of an account
accounts.getApiV1AccountsNameRatings

List ratings of an account
channelsSync.addVideoChannelSync

Create a synchronization for a video channel
channelsSync.delVideoChannelSync

Delete a video channel synchronization
channelsSync.triggerVideoChannelSync

Triggers the channel synchronization job, fetching all the videos from the remote channel
config.delCustomConfig

Delete instance runtime configuration
config.getAbout

Get instance "About" information
config.getConfig

Get instance public configuration
config.getCustomConfig

Get instance runtime configuration
config.putCustomConfig

Set instance runtime configuration
homepage.getApiV1CustomPagesHomepageInstance

Get instance custom homepage
homepage.putApiV1CustomPagesHomepageInstance

Set instance custom homepage
instanceFollows.deleteApiV1ServerFollowersNameWithHost

Remove or reject a follower to your server
instanceFollows.deleteApiV1ServerFollowingHostOrHandle

Unfollow an actor (PeerTube instance, channel or account)
instanceFollows.getApiV1ServerFollowers

List instances following the server
instanceFollows.getApiV1ServerFollowing

List instances followed by the server
instanceFollows.postApiV1ServerFollowersNameWithHostAccept

Accept a pending follower to your server
instanceFollows.postApiV1ServerFollowersNameWithHostReject

Reject a pending follower to your server
instanceFollows.postApiV1ServerFollowing

Follow a list of actors (PeerTube instance, channel or account)
instanceRedundancy.putApiV1ServerRedundancyHost

Update a server redundancy policy
job.getJobs

List instance jobs
job.postApiV1JobsPause

Pause job queue
job.postApiV1JobsResume

Resume job queue
liveVideos.addLive

Create a live
liveVideos.getApiV1VideosIdLiveSession

If the video is a replay of a live, you can find the associated live session using this endpoint
liveVideos.getApiV1VideosLiveIdSessions

List all sessions created in a particular live
liveVideos.getLiveId

Get information about a live
liveVideos.updateLiveId

Update information about a live
logs.getInstanceAuditLogs

Get instance audit logs
logs.getInstanceLogs

Get instance logs
logs.sendClientLog

Send client log
myHistory.deleteApiV1UsersMeHistoryVideosVideoId

Delete history element
myHistory.getApiV1UsersMeHistoryVideos

List watched videos history
myHistory.postApiV1UsersMeHistoryVideosRemove

Clear video history
myNotifications.getApiV1UsersMeNotifications

List my notifications
myNotifications.postApiV1UsersMeNotificationsRead

Mark notifications as read by their id
myNotifications.postApiV1UsersMeNotificationsReadAll

Mark all my notification as read
myNotifications.putApiV1UsersMeNotificationSettings

Update my notification settings
mySubscriptions.deleteApiV1UsersMeSubscriptionsSubscriptionHandle

Delete subscription of my user
mySubscriptions.getApiV1UsersMeSubscriptions

Get my user subscriptions
mySubscriptions.getApiV1UsersMeSubscriptionsExist

Get if subscriptions exist for my user
mySubscriptions.getApiV1UsersMeSubscriptionsSubscriptionHandle

Get subscription of my user
mySubscriptions.getApiV1UsersMeSubscriptionsVideos

List videos of subscriptions of my user
mySubscriptions.postApiV1UsersMeSubscriptions

Add subscription to my user
myUser.deleteApiV1UsersMeAvatar

Delete my avatar
myUser.getApiV1UsersMeVideoQuotaUsed

Get my user used quota
myUser.getApiV1UsersMeVideos

Get videos of my user
myUser.getApiV1UsersMeVideosVideoIdRating

Get rate of my user for a video
myUser.getUserInfo

Get my user information
myUser.postApiV1UsersMeAvatarPick

Update my user avatar
myUser.putUserInfo

Update my user information
plugins.addPlugin

Install a plugin
plugins.getApiV1PluginsNpmNamePublicSettings

Get a plugin's public settings
plugins.getApiV1PluginsNpmNameRegisteredSettings

Get a plugin's registered settings
plugins.getAvailablePlugins

List available plugins
plugins.getPlugin

Get a plugin
plugins.getPlugins

List plugins
plugins.putApiV1PluginsNpmNameSettings

Set a plugin's settings
plugins.uninstallPlugin

Uninstall a plugin
plugins.updatePlugin

Update a plugin
register.acceptRegistration

Accept registration
register.deleteRegistration

Delete the registration entry. It will not remove the user associated with this registration (if any)
register.listRegistrations

List registrations
register.registerUser

Signup has to be enabled and signup approval is not required
register.rejectRegistration

Reject registration
register.requestRegistration

Signup has to be enabled and require approval on the instance
register.resendEmailToVerifyRegistration

Resend verification link to registration email
register.verifyRegistrationEmail

Following a user registration request, the user will receive an email asking to click a link containing a secret.
search.searchChannels

Search channels
search.searchPlaylists

Search playlists
search.searchVideos

Search videos
serverBlocks.deleteApiV1ServerBlocklistServersHost

Unblock a server by its domain
serverBlocks.getApiV1ServerBlocklistServers

List server blocks
serverBlocks.postApiV1ServerBlocklistServers

Block a server
session.getOAuthClient

You need to retrieve a client id and secret before .
session.getOAuthToken

With your , you can retrieve an access and refresh tokens.
session.revokeOAuthToken

Revokes your access token and its associated refresh token, destroying your current session.
staticVideoFiles.getStaticStreamingPlaylistsHlsFilename

Get public HLS video file
staticVideoFiles.getStaticStreamingPlaylistsHlsPrivateFilename

Get private HLS video file
staticVideoFiles.getStaticWebseedFilename

Get public WebTorrent video file
staticVideoFiles.getStaticWebseedPrivateFilename

Get private WebTorrent video file
stats.getInstanceStats

Get instance public statistics. This endpoint is cached.
stats.postApiV1MetricsPlayback

These metrics are exposed by OpenTelemetry metrics exporter if enabled.
users.addUser

Create a user
users.confirmTwoFactorRequest

Confirm a two factor authentication request
users.delUser

Delete a user
users.disableTwoFactor

Disable two factor authentication of a user
users.getUser

Get a user
users.getUsers

List users
users.putUser

Update a user
users.requestTwoFactor

Request two factor authentication for a user
users.resendEmailToVerifyUser

Resend user verification link
users.verifyUser

Following a user registration, the new user will receive an email asking to click a link containing a secret. This endpoint can also be used to verify a new email set in the user account.
video.addView

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.
video.delVideo

Delete a video
video.getCategories

List available video categories
video.getLanguages

List available video languages
video.getLicences

List available video licences
video.getPrivacyPolicies

List available video privacy policies
video.getVideo

Get a video
video.getVideoChannelVideos

List videos of a video channel
video.getVideoDesc

Get complete video description
video.getVideos

List videos
video.getVideoSource

Get video source file metadata
video.putApiV1VideosIdWatching

This endpoint has been deprecated. Use /videos/{id}/views instead
video.putVideo

Update a video
video.requestVideoToken

Request special tokens that expire quickly to use them in some context (like accessing private static files)
video.uploadLegacy

Uses a single request to upload a video.
video.uploadResumable

Uses to continue, pause or resume the upload of a video
video.uploadResumableCancel

Uses to cancel the upload of a video
video.uploadResumableInit

Uses to initialize the upload of a video
videoBlocks.addVideoBlock

Block a video
videoBlocks.delVideoBlock

Unblock a video by its id
videoBlocks.getVideoBlocks

List video blocks
videoCaptions.addVideoCaption

Add or replace a video caption
videoCaptions.delVideoCaption

Delete a video caption
videoCaptions.getVideoCaptions

List captions of a video
videoChannels.addVideoChannel

Create a video channel
videoChannels.deleteApiV1VideoChannelsChannelHandleAvatar

Delete channel avatar
videoChannels.deleteApiV1VideoChannelsChannelHandleBanner

Delete channel banner
videoChannels.delVideoChannel

Delete a video channel
videoChannels.getApiV1AccountsNameVideoChannels

List video channels of an account
videoChannels.getApiV1AccountsNameVideoChannelSyncs

List the synchronizations of video channels of an account
videoChannels.getVideoChannel

Get a video channel
videoChannels.getVideoChannelFollowers

List followers of a video channel
videoChannels.getVideoChannels

List video channels
videoChannels.postApiV1VideoChannelsChannelHandleAvatarPick

Update channel avatar
videoChannels.postApiV1VideoChannelsChannelHandleBannerPick

Update channel banner
videoChannels.postApiV1VideoChannelsChannelHandleImportVideos

Import a remote channel/playlist videos into a channel
videoChannels.putVideoChannel

Update a video channel
videoComments.deleteApiV1VideosIdCommentsCommentId

Delete a comment or a reply
videoComments.getApiV1VideosIdCommentThreads

List threads of a video
videoComments.getApiV1VideosIdCommentThreadsThreadId

Get a thread
videoComments.postApiV1VideosIdCommentsCommentId

Reply to a thread of a video
videoComments.postApiV1VideosIdCommentThreads

Create a thread
videoFeeds.getSyndicatedComments

List comments on videos
videoFeeds.getSyndicatedSubscriptionVideos

List videos of subscriptions tied to a token
videoFeeds.getSyndicatedVideos

List videos
videoFiles.delVideoHls

Delete video HLS files
videoFiles.delVideoWebTorrent

Delete video WebTorrent files
videoImports.deleteApiV1VideosImportsId

Delete ended video import
videoImports.importVideo

Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
videoImports.postApiV1VideosImportsIdCancel

Cancel a pending video import
videoMirroring.delMirroredVideo

Delete a mirror done on a video
videoMirroring.getMirroredVideos

List videos being mirrored
videoMirroring.putMirroredVideo

Mirror a video
videoOwnershipChange.getApiV1VideosOwnership

List video ownership changes
videoOwnershipChange.postApiV1VideosIdGiveOwnership

Request ownership change
videoOwnershipChange.postApiV1VideosOwnershipIdAccept

Accept ownership change request
videoOwnershipChange.postApiV1VideosOwnershipIdRefuse

Refuse ownership change request
videoPlaylists.addPlaylist

If the video playlist is set as public, videoChannelId is mandatory.
videoPlaylists.deleteApiV1VideoPlaylistsPlaylistId

Delete a video playlist
videoPlaylists.delVideoPlaylistVideo

Delete an element from a playlist
videoPlaylists.getApiV1AccountsNameVideoPlaylists

List playlists of an account
videoPlaylists.getApiV1UsersMeVideoPlaylistsVideosExist

Check video exists in my playlists
videoPlaylists.getApiV1VideoChannelsChannelHandleVideoPlaylists

List playlists of a channel
videoPlaylists.getApiV1VideoPlaylistsPlaylistId

Get a video playlist
videoPlaylists.getPlaylistPrivacyPolicies

List available playlist privacy policies
videoPlaylists.getPlaylists

List video playlists
videoPlaylists.putApiV1VideoPlaylistsPlaylistId

If the video playlist is set as public, the playlist must have a assigned channel.
videoPlaylists.putVideoPlaylistVideo

Update a playlist element
videoPlaylists.reorderVideoPlaylist

Reorder a playlist
videoRates.putApiV1VideosIdRate

Like/dislike a video
videos.addVideoPlaylistVideo

Add a video in a playlist
videos.getApiV1UsersMeVideosImports

Get video imports of my user
videos.getVideoPlaylistVideos

List videos of a playlist
videoStats.getApiV1VideosIdStatsOverall

Get overall stats of a video
videoStats.getApiV1VideosIdStatsRetention

Get retention stats of a video
videoStats.getApiV1VideosIdStatsTimeseriesMetric

Get timeserie stats of a video
videoTranscoding.createVideoTranscoding

Create a transcoding job
videoTranscoding.postApiV1VideosIdStudioEdit

Create a task to edit a video (cut, add intro/outro etc)
openapi.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools