Users

List users

GET
https://peertube2.cpy.re/api/v1/users

Parameters

searchstringquery

Plain text search that will match with user usernames or emails

blockedbooleanquery

Filter results down to (un)banned users

roleUserRole012query

Filter results down to users with a specific role

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

sortstring-id-username-createdAtquery

Sort users by criteria

Response

200OKArray<User>

successful operation

Response fields application/json
Array<User>
Show child attributes
idid>= 1
Example
42
usernameusername

immutable name of the user, used to find or mention its actor

Example
chocobozzz
emailemail<email>

The user email

emailVerifiedboolean

Has the user confirmed their email address?

nsfwPolicyNSFWPolicydisplaywarndo_not_list
nsfwFlagsDisplayedNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
nsfwFlagsHiddenNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
nsfwFlagsWarnedNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
nsfwFlagsBlurredNSFWFlag0124

NSFW flags (can be combined using bitwise or operator)

  • 0 NONE
  • 1 VIOLENT
  • 2 EXPLICIT_SEX
aiUsagesHiddenArray<VideoAIUsageSet>1234

PeerTube >= 9.0 Videos with these AI usages are hidden from video lists

adminFlagsUserAdminFlags01

Admin flags for the user (None = 0, Bypass video blocklist = 1)

Example
1
autoPlayNextVideoboolean

Automatically start playing the upcoming video after the currently playing video

autoPlayNextVideoPlaylistboolean

Automatically start playing the video on the playlist after the currently playing video

autoPlayVideoboolean

Automatically start playing the video on the watch page

p2pEnabledboolean

whether to enable P2P in the player or not

videosHistoryEnabledboolean

whether to keep track of watched history or not

videoLanguagesArray<string>

list of languages to filter videos down to

videoCategoriesArray<integer> | null

list of categories to filter videos down to (null means all categories)

videoLivestringtruefalseboth

filter videos down to lives (true), VODs (false) or display both

languagestring

default language for this user

videoQuotainteger

The user video quota in bytes

Example
-1
videoQuotaDailyinteger

The user daily video quota in bytes

Example
-1
roleobject
Show child attributes
idUserRole012

The user role (Admin = 0, Moderator = 1, User = 2)

Example
2
labelstringUserModeratorAdministrator
themestring

Theme enabled by this user

accountActor & any
Show child attributes
idid>= 1
Example
42
urlstring<url>
nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username
Example
chocobozzz
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>
hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>
updatedAtstring<date-time>
userIdid | null

object id for the user tied to this account

Show child attributes
id>= 1
Example
42
displayNamestring

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

notificationSettingsUserNotificationSettings
Show child attributes
abuseAsModeratorNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
videoAutoBlacklistAsModeratorNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newUserRegistrationNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newVideoFromSubscriptionNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
blacklistOnMyVideoNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoPublishedNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoImportFinishedNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
commentMentionNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newCommentOnMyVideoNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newFollowNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newInstanceFollowerNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
autoInstanceFollowingNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
abuseStateChangeNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
abuseNewMessageNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newPeerTubeVersionNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newPluginVersionNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoStudioEditionFinishedNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoTranscriptionGeneratedNotificationSettingValue

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
videoChannelsArray<VideoChannel>
Show child attributes
idid>= 1
Example
42

Same fields as account.userId

urlstring<url>
nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username
Example
chocobozzz
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>
hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>
updatedAtstring<date-time>
displayNamestring

editable name of the channel, displayed in its representations

Example
Videos of Framasoft
descriptionstring | null
Example
Videos made with <3 by Framasoft
supportstring | null

text shown by default on all videos of this channel, to tell the audience how to support it

Example
Please support our work on https://soutenir.framasoft.org/en/ <3
publicEmailstring<email> | null

Public email visible in podcast RSS feeds

isLocalboolean
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>
ownerAccountActor & any
Show child attributes
idid>= 1
Example
42

Same fields as account.userId

urlstring<url>
nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username
Example
chocobozzz
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>
hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>
updatedAtstring<date-time>
userIdid | null

object id for the user tied to this account

Show child attributes
id>= 1
Example
42
displayNamestring

editable name of the account, displayed in its representations

descriptionstring | null

text or bio displayed on the account's profile

videosCountinteger

only included when withStats is true

viewsPerDayArray<object>

only included when withStats is true. Chronologically ordered, spans the whole statsDays range. Each point aggregates viewsGroupInterval worth of views, starting at date

Show child attributes
datestring<date-time>
viewsinteger
viewsGroupIntervalstringdayweekmonth

bucket size of viewsPerDay, only included when withStats is true

totalViewsinteger

lifetime views of all the channel videos, only included when withStats is true

blockedboolean
blockedReasonstring
noInstanceConfigWarningModalboolean
noAccountSetupWarningModalboolean
noWelcomeModalboolean
createdAtstring
pluginAuthstring

Auth plugin to use to authenticate the user

lastLoginDatestring<date-time>
twoFactorEnabledboolean

Whether the user has enabled two-factor authentication or not

newFeaturesInfoReadnumber

New features information the user has read

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
↑↓ navigate↵ selectesc close