Instance

Config

Each server exposes public information regarding supported videos and options.

Get instance public configuration

GET

https://peertube2.cpy.re/api/v1/config

Get instance public configuration

curl -X GET 'https://peertube2.cpy.re/api/v1/config'

const response = await fetch('https://peertube2.cpy.re/api/v1/config', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/config')
print(response.text)

200

External example: https://peertube2.cpy.re/api/v1/config

Response

200OKServerConfig

successful operation

Response fields application/json

instanceobject

Show child attributes

namestring

shortDescriptionstring

defaultClientRoutestring

isNSFWboolean

defaultNSFWPolicystring

serverCountrystring

defaultLanguagestring

supportobject

Show child attributes

textstring

customizationsobject

Show child attributes

javascriptstring

cssstring

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

bannersArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

searchobject

Show child attributes

remoteUriobject

Show child attributes

usersboolean

anonymousboolean

pluginobject

Show child attributes

registeredArray<string>

themeobject

Show child attributes

registeredArray<string>

emailobject

Show child attributes

enabledboolean

contactFormobject

Show child attributes

enabledboolean

serverVersionstring

serverCommitstring

transcodingobject

Show child attributes

hlsobject

Show child attributes

enabledboolean

web_videosobject

Show child attributes

enabledboolean

enabledResolutionsArray<VideoResolutionSet>

importobject

Show child attributes

videosobject

Show child attributes

httpobject

Show child attributes

enabledboolean

torrentobject

Show child attributes

enabledboolean

videoChannelSynchronizationobject

Show child attributes

enabledboolean

usersobject

Show child attributes

enabledboolean

resumableUploadobject

Show child attributes

minChunkSizenumber

In bytes. Minimum size of a user archive import chunk (except the last one), 0 if there is no minimum

exportobject

Show child attributes

usersobject

Show child attributes

enabledboolean

exportExpirationnumber

In milliseconds

maxUserVideoQuotanumber

In bytes

autoBlacklistobject

Show child attributes

videosobject

Show child attributes

ofUsersobject

Show child attributes

enabledboolean

blocklistobject

Show child attributes

publicLogobject

Show child attributes

enabledboolean

avatarobject

Show child attributes

fileobject

Show child attributes

sizeobject

Show child attributes

maxinteger

extensionsArray<string>

videoobject

Show child attributes

imageobject

Show child attributes

extensionsArray<string>

sizeobject

Show child attributes

maxinteger

fileobject

Show child attributes

extensionsArray<string>

videoCaptionobject

Show child attributes

fileobject

Show child attributes

sizeobject

Show child attributes

maxinteger

extensionsArray<string>

userobject

Show child attributes

videoQuotainteger

In bytes

Example

16810141515

videoQuotaDailyinteger

In bytes

Example

1681014151

trackerobject

Show child attributes

enabledboolean

followingsobject

Show child attributes

instanceobject

Show child attributes

autoFollowIndexobject

Show child attributes

indexUrlstring<url>

federationobject

Show child attributes

enabledboolean

homepageobject

Show child attributes

enabledboolean

openTelemetryobject

PeerTube >= 6.1

Show child attributes

metricsobject

Show child attributes

enabledboolean

playbackStatsIntervalnumber

Milliseconds

viewsobject

PeerTube >= 6.1

Show child attributes

videosobject

Show child attributes

countViewAfternumber

Milliseconds

watchingIntervalobject

Show child attributes

anonymousnumber

Milliseconds

usersnumber

Milliseconds

Get instance "About" information

GET

https://peertube2.cpy.re/api/v1/config/about

Translatable information is returned in the language of the request, using the x-peertube-language header or the Accept-Language header. If the instance has no translation for this language, the default information is returned.

Get instance "About" information

curl -X GET 'https://peertube2.cpy.re/api/v1/config/about'

const response = await fetch('https://peertube2.cpy.re/api/v1/config/about', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/config/about')
print(response.text)

200

External example: https://peertube2.cpy.re/api/v1/config/about

Parameters

Response

200OKServerConfigAbout

successful operation

Response fields application/json

instanceobject

Show child attributes

namestring

shortDescriptionstring

descriptionstring

termsstring

codeOfConductstring

hardwareInformationstring

creationReasonstring

moderationInformationstring

administratorstring

maintenanceLifetimestring

businessModelstring

supportobject

Show child attributes

textstring

languagesArray<string>

categoriesArray<integer>

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

bannersArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

Get instance runtime configuration

GET

https://peertube2.cpy.re/api/v1/config/custom

Get instance runtime configuration

curl -X GET 'https://peertube2.cpy.re/api/v1/config/custom' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/config/custom', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://peertube2.cpy.re/api/v1/config/custom',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "instance": {
    "name": "string",
    "shortDescription": "string",
    "description": "string",
    "terms": "string",
    "codeOfConduct": "string",
    "creationReason": "string",
    "moderationInformation": "string",
    "administrator": "string",
    "maintenanceLifetime": "string",
    "businessModel": "string",
    "hardwareInformation": "string",
    "translations": [
      {
        "language": "fr-FR",
        "shortDescription": "string",
        "description": "string",
        "terms": "string",
        "codeOfConduct": "string",
        "moderationInformation": "string",
        "administrator": "string",
        "creationReason": "string",
        "maintenanceLifetime": "string",
        "businessModel": "string",
        "hardwareInformation": "string",
        "supportText": "string"
      }
    ],
    "languages": [
      "string"
    ],
    "categories": [
      0
    ],
    "isNSFW": true,
    "defaultNSFWPolicy": "string",
    "serverCountry": "string",
    "support": {
      "text": "string"
    },
    "social": {
      "externalLink": "string",
      "mastodonLink": "string",
      "blueskyLink": "string",
      "xLink": "string"
    },
    "defaultClientRoute": "string",
    "customizations": {
      "javascript": "string",
      "css": "string"
    }
  },
  "theme": {
    "default": "string"
  },
  "services": {
    "twitter": {
      "username": "string"
    }
  },
  "cache": {
    "previews": {
      "size": 0
    },
    "captions": {
      "size": 0
    }
  },
  "signup": {
    "enabled": true,
    "limit": 0,
    "requiresEmailVerification": true
  },
  "admin": {
    "email": "user@example.com"
  },
  "contactForm": {
    "enabled": true
  },
  "user": {
    "videoQuota": 16810141515,
    "videoQuotaDaily": 1681014151
  },
  "transcoding": {
    "enabled": true,
    "originalFile": {
      "keep": true
    },
    "allowAdditionalExtensions": true,
    "allowAudioFiles": true,
    "threads": 0,
    "concurrency": 0,
    "profile": "default",
    "resolutions": {
      "0p": true,
      "144p": true,
      "240p": true,
      "360p": true,
      "480p": true,
      "720p": true,
      "1080p": true,
      "1440p": true,
      "2160p": true
    },
    "web_videos": {
      "enabled": true
    },
    "hls": {
      "enabled": true,
      "splitAudioAndVideo": true
    }
  },
  "import": {
    "videos": {
      "http": {
        "enabled": true
      },
      "torrent": {
        "enabled": true
      }
    },
    "video_channel_synchronization": {
      "enabled": true
    }
  },
  "autoBlacklist": {
    "videos": {
      "ofUsers": {
        "enabled": true
      }
    }
  },
  "blocklist": {
    "publicLog": {
      "enabled": true
    }
  },
  "followers": {
    "instance": {
      "enabled": true,
      "manualApproval": true
    }
  },
  "storyboard": {
    "enabled": true
  },
  "defaults": {
    "publish": {
      "downloadEnabled": true,
      "commentsPolicy": 1,
      "recommendationScope": 1,
      "privacy": 1,
      "licence": 2
    },
    "p2p": {
      "webapp": {
        "enabled": true
      },
      "embed": {
        "enabled": true
      }
    },
    "player": {
      "autoPlay": true
    }
  }
}

Response

200OKServerConfigCustom

successful operation

Response fields application/json

instanceobject

Show child attributes

namestring

shortDescriptionstring

descriptionstring

termsstring

codeOfConductstring

creationReasonstring

moderationInformationstring

administratorstring

maintenanceLifetimestring

businessModelstring

hardwareInformationstring

translationsArray<InstanceTranslation>

Translations of the instance information. Empty fields fall back to the default instance information

Show child attributes

languagestring

Locale of the web interface

Example

fr-FR

shortDescriptionstring

descriptionstring

termsstring

codeOfConductstring

moderationInformationstring

administratorstring

creationReasonstring

maintenanceLifetimestring

businessModelstring

hardwareInformationstring

supportTextstring

languagesArray<string>

categoriesArray<number>

isNSFWboolean

defaultNSFWPolicystring

serverCountrystring

supportobject

Show child attributes

textstring

defaultClientRoutestring

customizationsobject

Show child attributes

javascriptstring

cssstring

themeobject

Show child attributes

defaultstring

servicesobject

Show child attributes

twitterobject

Show child attributes

usernamestring

cacheobject

Show child attributes

previewsobject

Show child attributes

sizeinteger

captionsobject

Show child attributes

sizeinteger

adminobject

Show child attributes

emailstring<email>

contactFormobject

Show child attributes

enabledboolean

userobject

Settings that apply to new users, if registration is enabled

Show child attributes

videoQuotainteger

Example

16810141515

videoQuotaDailyinteger

Example

1681014151

transcodingobject

Settings pertaining to transcoding jobs

Show child attributes

enabledboolean

originalFileobject

Show child attributes

keepboolean

allowAdditionalExtensionsboolean

Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos

allowAudioFilesboolean

If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file

threadsinteger

Amount of threads used by ffmpeg for 1 transcoding job

concurrencynumber

Amount of transcoding jobs to execute in parallel

profilestringdefault

New profiles can be added by plugins ; available in core PeerTube: 'default'.

resolutionsobject

Resolutions to transcode new videos to

Show child attributes

0pboolean

144pboolean

240pboolean

360pboolean

480pboolean

720pboolean

1080pboolean

1440pboolean

2160pboolean

web_videosobject

Web Video specific settings

Show child attributes

enabledboolean

hlsobject

HLS specific settings

Show child attributes

enabledboolean

splitAudioAndVideoboolean

importobject

Show child attributes

videosobject

Show child attributes

httpobject

Show child attributes

enabledboolean

torrentobject

Show child attributes

enabledboolean

video_channel_synchronizationobject

Show child attributes

enabledboolean

autoBlacklistobject

Show child attributes

videosobject

Show child attributes

ofUsersobject

Show child attributes

enabledboolean

blocklistobject

Show child attributes

publicLogobject

Show child attributes

enabledboolean

followersobject

Show child attributes

instanceobject

Show child attributes

enabledboolean

manualApprovalboolean

storyboardobject

Show child attributes

enabledboolean

defaultsobject

Show child attributes

publishobject

Show child attributes

downloadEnabledboolean

commentsPolicyVideoCommentsPolicySet123

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

recommendationScopeVideoRecommendationScopeSet1234

Videos that can be recommended next to a video:

1 All videos
2 Only videos of the platform that owns the reference video (or of the current platform if no video is given)
3 Only videos of the account that owns the reference video
4 Only videos of the channel of the reference video

This is a preference of the video owner: applications displaying recommendations may not apply it

privacyVideoPrivacySet12345

privacy id of the video (see /videos/privacies)

licenceVideoLicenceSet

licence id of the video (see /videos/licences)

Example

p2pobject

Show child attributes

webappobject

Show child attributes

enabledboolean

embedobject

Show child attributes

enabledboolean

playerobject

Show child attributes

autoPlayboolean

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Set instance runtime configuration

PUT

https://peertube2.cpy.re/api/v1/config/custom

Changing instance.customizations.javascript or instance.customizations.css requires a password confirmation: set currentPassword at the root of the request body.

Set instance runtime configuration

curl -X PUT 'https://peertube2.cpy.re/api/v1/config/custom' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/config/custom', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.put(
    'https://peertube2.cpy.re/api/v1/config/custom',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OK

successful operation

400Bad Request

Arises when:

the emailer is disabled and the instance is open to registrations
web videos and hls are disabled with transcoding enabled - you need at least one enabled
the custom JavaScript or CSS changed and currentPassword is missing

403Forbidden

invalid currentPassword, or password confirmation unavailable for this user

429Too Many Requests

too many failed password confirmations

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Delete instance runtime configuration

DELETE

https://peertube2.cpy.re/api/v1/config/custom

Delete instance runtime configuration

curl -X DELETE 'https://peertube2.cpy.re/api/v1/config/custom' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/config/custom', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/config/custom',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OK

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Update instance banner

POST

https://peertube2.cpy.re/api/v1/config/instance-banner/pick

Update instance banner

curl -X POST 'https://peertube2.cpy.re/api/v1/config/instance-banner/pick' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const form = new FormData();
const response = await fetch('https://peertube2.cpy.re/api/v1/config/instance-banner/pick', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
    ]
    response = requests.request('POST', 'https://peertube2.cpy.re/api/v1/config/instance-banner/pick', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "bannerfile": "<binary>"
}

Body

multipart/form-data

multipart/form-dataobject

Encoding

bannerfileimage/png, image/jpeg

bannerfilestring<binary>

The file to upload.

Response

204No Content

successful operation

413Payload Too Large

image file too large

Response headers

X-File-Maximum-Sizestring<Nginx size>header

Maximum file size for the banner

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Delete instance banner

DELETE

https://peertube2.cpy.re/api/v1/config/instance-banner

Delete instance banner

curl -X DELETE 'https://peertube2.cpy.re/api/v1/config/instance-banner' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/config/instance-banner', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/config/instance-banner',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Update instance avatar

POST

https://peertube2.cpy.re/api/v1/config/instance-avatar/pick

Update instance avatar

curl -X POST 'https://peertube2.cpy.re/api/v1/config/instance-avatar/pick' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const form = new FormData();
const response = await fetch('https://peertube2.cpy.re/api/v1/config/instance-avatar/pick', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
    ]
    response = requests.request('POST', 'https://peertube2.cpy.re/api/v1/config/instance-avatar/pick', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "avatarfile": "<binary>"
}

Body

multipart/form-data

multipart/form-dataobject

Encoding

avatarfileimage/png, image/jpeg

avatarfilestring<binary>

The file to upload.

Response

204No Content

successful operation

413Payload Too Large

image file too large

Response headers

X-File-Maximum-Sizestring<Nginx size>header

Maximum file size for the avatar

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Delete instance avatar

DELETE

https://peertube2.cpy.re/api/v1/config/instance-avatar

Delete instance avatar

curl -X DELETE 'https://peertube2.cpy.re/api/v1/config/instance-avatar' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/config/instance-avatar', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/config/instance-avatar',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

204No Content

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Update instance logo

POST

https://peertube2.cpy.re/api/v1/config/instance-logo/{logoType}/pick

Update instance logo

curl -X POST 'https://peertube2.cpy.re/api/v1/config/instance-logo/favicon/pick' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const form = new FormData();
const response = await fetch('https://peertube2.cpy.re/api/v1/config/instance-logo/favicon/pick', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
    ]
    response = requests.request('POST', 'https://peertube2.cpy.re/api/v1/config/instance-logo/favicon/pick', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "logofile": "<binary>"
}

Body

multipart/form-data

multipart/form-dataobject

Encoding

logofileimage/png, image/jpeg

logofilestring<binary>

The file to upload.

Parameters

logoTypestringfaviconheader-wideheader-squareopengraphrequiredpath

Response

204No Content

successful operation

413Payload Too Large

image file too large

Response headers

X-File-Maximum-Sizestring<Nginx size>header

Maximum file size for the banner

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Delete instance logo

DELETE

https://peertube2.cpy.re/api/v1/config/instance-logo/{logoType}

Delete instance logo

curl -X DELETE 'https://peertube2.cpy.re/api/v1/config/instance-logo/favicon' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/config/instance-logo/favicon', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/config/instance-logo/favicon',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

logoTypestringfaviconheader-wideheader-squareopengraphrequiredpath

Response

204No Content

successful operation

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Docs by Sourcey