PeerTube API Reference

Introduction

The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. You can use your favorite HTTP/REST library for your programming language to use PeerTube. No official SDK is currently provided.

Authentication

When you sign up for an account, you are given the possibility to generate sessions, and authenticate using this session token. One session token can currently be used at a time.

API Endpoint
https://peertube.example.com/api/v1
Request Content-Types: application/json
Response Content-Types: application/json; charset=utf-8
Schemes: https
Version: 1.1.0-alpha.2

Authentication

OAuth2

In the header: Authorization: Bearer <token>

Authenticating via OAuth requires the following steps:

  • Have an account with sufficient authorization levels
  • Generate a Bearer Token
  • Make Authenticated Requests
type
oauth2
flow
password
tokenUrl
https://peertube.example.com/api/v1/users/token
scopes
admin

Admin scope

moderator

Moderator scope

user

User scope

Accounts

Using some features of PeerTube require authentication, for which Accounts provide different levels of permission as well as associated user information. Accounts also encompass remote accounts discovered across the federation.

Accounts

Get the account by name

GET /accounts/{name}
name: string
in path

The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for example)

start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
Account

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "displayName": "string",
  "id": "number",
  "uuid": "string",
  "url": "string",
  "name": "string",
  "host": "string",
  "followingCount": "number",
  "followersCount": "number",
  "createdAt": "string",
  "updatedAt": "string",
  "avatar": {
    "path": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
Accounts Video

Get videos for an account, provided the name of that account

GET /accounts/{name}/videos
name: string
in path

The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for example)

200 OK
Video

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "number",
  "uuid": "string",
  "createdAt": "string",
  "publishedAt": "string",
  "updatedAt": "string",
  "category": {
    "id": "number",
    "label": "string"
  },
  "licence": {
    "id": "number",
    "label": "string"
  },
  "language": {
    "id": "string",
    "label": "string"
  },
  "privacy": "string",
  "description": "string",
  "duration": "number",
  "isLocal": "boolean",
  "name": "string",
  "thumbnailPath": "string",
  "previewPath": "string",
  "embedPath": "string",
  "views": "number",
  "likes": "number",
  "dislikes": "number",
  "nsfw": "boolean",
  "account": {
    "name": "string",
    "displayName": "string",
    "url": "string",
    "host": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  }
}
Accounts

Get all accounts

GET /accounts
200 OK
Account

successful operation

type
Account
Response Content-Types: application/jsonhttps://peertube.cpy.re/api/v1
Response Example (200 OK) 
[
  {
    "displayName": "string",
    "id": "number",
    "uuid": "string",
    "url": "string",
    "name": "string",
    "host": "string",
    "followingCount": "number",
    "followersCount": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  }
]

Config

Each server exposes public information regarding supported videos and options.

Config

Get the configuration of the server

GET /config
200 OK
ServerConfig

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "signup": {
    "allowed": "boolean"
  },
  "transcoding": {
    "enabledResolutions": [
      "number"
    ]
  },
  "avatar": {
    "file": {
      "size": {
        "max": "number"
      }
    },
    "extensions": [
      "string"
    ]
  },
  "video": {
    "file": {
      "extensions": [
        "string"
      ]
    }
  }
}

Feeds

Feeds of videos and feeds of comments allow to see updates and get them in an aggregator or script of your choice.

Feeds

Get the feed of videos for the server, with optional filter by account name or id

GET /feeds/videos.{format}
format: string xml, atom, json xml
in path

The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and json to JSON FEED 1.0

accountId: number
in query

The id of the local account to filter to (beware, users IDs and not actors IDs which will return empty feeds

accountName: string
in query

The name of the local account to filter to

200 OK

successful operation

Response Content-Types: application/atom+xml, application/rss+xml, application/json

Job

Jobs are long-running tasks enqueued and processed by the instance itself. No additional worker registration is currently available.

Job

Get list of jobs

GET /jobs
state: string
in path

The state of the job

start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
Job

successful operation

type
Job
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "state": "string",
    "category": "string",
    "handlerName": "string",
    "handlerInputData": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
]
OAuth2 admin

ServerFollowing

Managing servers which the instance interacts with is crucial to the concept of federation in PeerTube and external video indexation. The PeerTube server then deals with inter-server ActivityPub operations and propagates information across its social graph by posting activities to actors' inbox endpoints.

ServerFollowing

Unfollow a server by hostname

DELETE /server/following/{host}
host: string
in path

The host to unfollow

201 Created

successful operation

Response Content-Types: application/json
OAuth2 admin
ServerFollowing

Get followers of the server

GET /server/followers
start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
Follow

successful operation

type
Follow
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "follower": {
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    },
    "following": {
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    },
    "score": "number",
    "state": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
]
ServerFollowing

Get servers followed by the server

GET /server/following
start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
Follow

successful operation

type
Follow
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "follower": {
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    },
    "following": {
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    },
    "score": "number",
    "state": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
]
ServerFollowing

Follow a server

POST /server/following
Follow

undefined

Request Content-Types: application/json
Request Example
{
  "id": "number",
  "follower": {
    "id": "number",
    "uuid": "string",
    "url": "string",
    "name": "string",
    "host": "string",
    "followingCount": "number",
    "followersCount": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  },
  "following": {
    "id": "number",
    "uuid": "string",
    "url": "string",
    "name": "string",
    "host": "string",
    "followingCount": "number",
    "followersCount": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  },
  "score": "number",
  "state": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
204 No Content

Successful operation

Response Content-Types: application/json
OAuth2 admin

VideoAbuse

Video abuses deal with reports of local or remote videos alike.

VideoAbuse

Get list of reported video abuses

GET /videos/abuse
start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
VideoAbuse

successful operation

type
VideoAbuse
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "reason": "string",
    "reporterAccount": {
      "displayName": "string",
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    },
    "video": {
      "id": "number",
      "name": "string",
      "uuid": "string",
      "url": "string"
    },
    "createdAt": "string"
  }
]
OAuth2
VideoAbuse

Report an abuse, on a video by its id

POST /videos/{id}/abuse
id: string
in path

The video id or uuid

204 No Content

Successful operation

Response Content-Types: application/json
OAuth2

Video

Operations dealing with listing, uploading, fetching or modifying videos.

Accounts Video

Get videos for an account, provided the name of that account

GET /accounts/{name}/videos
name: string
in path

The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for example)

200 OK
Video

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "number",
  "uuid": "string",
  "createdAt": "string",
  "publishedAt": "string",
  "updatedAt": "string",
  "category": {
    "id": "number",
    "label": "string"
  },
  "licence": {
    "id": "number",
    "label": "string"
  },
  "language": {
    "id": "string",
    "label": "string"
  },
  "privacy": "string",
  "description": "string",
  "duration": "number",
  "isLocal": "boolean",
  "name": "string",
  "thumbnailPath": "string",
  "previewPath": "string",
  "embedPath": "string",
  "views": "number",
  "likes": "number",
  "dislikes": "number",
  "nsfw": "boolean",
  "account": {
    "name": "string",
    "displayName": "string",
    "url": "string",
    "host": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  }
}
Video

Get list of videos

GET /videos
category: number
in query

category id of the video

start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
Video

successful operation

type
Video
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "uuid": "string",
    "createdAt": "string",
    "publishedAt": "string",
    "updatedAt": "string",
    "category": {
      "id": "number",
      "label": "string"
    },
    "licence": {
      "id": "number",
      "label": "string"
    },
    "language": {
      "id": "string",
      "label": "string"
    },
    "privacy": "string",
    "description": "string",
    "duration": "number",
    "isLocal": "boolean",
    "name": "string",
    "thumbnailPath": "string",
    "previewPath": "string",
    "embedPath": "string",
    "views": "number",
    "likes": "number",
    "dislikes": "number",
    "nsfw": "boolean",
    "account": {
      "name": "string",
      "displayName": "string",
      "url": "string",
      "host": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    }
  }
]
Video

Get list of video licences known by the server

GET /videos/categories
200 OK

successful operation

type
string[]
Response Content-Types: application/json
Response Example (200 OK) 
[
  "string"
]
Video

Get list of video licences known by the server

GET /videos/licences
200 OK

successful operation

type
string[]
Response Content-Types: application/json
Response Example (200 OK) 
[
  "string"
]
Video

Get list of languages known by the server

GET /videos/languages
200 OK

successful operation

type
string[]
Response Content-Types: application/json
Response Example (200 OK) 
[
  "string"
]
Video

Get list of privacy policies supported by the server

GET /videos/privacies
200 OK

successful operation

type
string[]
Response Content-Types: application/json
Response Example (200 OK) 
[
  "string"
]
Video

Update metadata for a video by its id

PUT /videos/{id}
id: string
in path

The video id or uuid

thumbnailfile: file
in formData

Video thumbnail file

previewfile: file
in formData

Video preview file

category: number
in formData

Video category

licence: number
in formData

Video licence

language: string
in formData

Video language

description: string
in formData

Video description

waitTranscoding: boolean
in formData

Whether or not we wait transcoding before publish the video

support: string
in formData

Text describing how to support the video uploader

nsfw: boolean
in formData

Whether or not this video contains sensitive content

name: string
in formData

Video name

tags: string[]
in formData

Video tags

commentsEnabled: boolean
in formData

Enable or disable comments for this video

privacy: string Public, Unlisted
in formData

Video privacy

scheduleUpdate: object
in formData

Schedule an update at a specific datetime

200 OK
Video

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "number",
  "uuid": "string",
  "createdAt": "string",
  "publishedAt": "string",
  "updatedAt": "string",
  "category": {
    "id": "number",
    "label": "string"
  },
  "licence": {
    "id": "number",
    "label": "string"
  },
  "language": {
    "id": "string",
    "label": "string"
  },
  "privacy": "string",
  "description": "string",
  "duration": "number",
  "isLocal": "boolean",
  "name": "string",
  "thumbnailPath": "string",
  "previewPath": "string",
  "embedPath": "string",
  "views": "number",
  "likes": "number",
  "dislikes": "number",
  "nsfw": "boolean",
  "account": {
    "name": "string",
    "displayName": "string",
    "url": "string",
    "host": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  }
}
OAuth2
Video

Get a video by its id

GET /videos/{id}
id: string
in path

The video id or uuid

200 OK
Video

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "number",
  "uuid": "string",
  "createdAt": "string",
  "publishedAt": "string",
  "updatedAt": "string",
  "category": {
    "id": "number",
    "label": "string"
  },
  "licence": {
    "id": "number",
    "label": "string"
  },
  "language": {
    "id": "string",
    "label": "string"
  },
  "privacy": "string",
  "description": "string",
  "duration": "number",
  "isLocal": "boolean",
  "name": "string",
  "thumbnailPath": "string",
  "previewPath": "string",
  "embedPath": "string",
  "views": "number",
  "likes": "number",
  "dislikes": "number",
  "nsfw": "boolean",
  "account": {
    "name": "string",
    "displayName": "string",
    "url": "string",
    "host": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  }
}
Video

Delete a video by its id

DELETE /videos/{id}
id: string
in path

The video id or uuid

204 No Content

Successful operation

Response Content-Types: application/json
OAuth2
Video

Get a video description by its id

GET /videos/{id}/description
id: string
in path

The video id or uuid

200 OK

successful operation

type
string
Response Content-Types: application/json
Response Example (200 OK) 
"string"
Video

Add a view to the video by its id

POST /videos/{id}/views
id: string
in path

The video id or uuid

204 No Content

Successful operation

Response Content-Types: application/json
Video

Upload a video file with its metadata

POST /videos/upload
videofile: file
in formData

Video file

channelId: number
in formData

Channel id that will contain this video

thumbnailfile: file
in formData

Video thumbnail file

previewfile: file
in formData

Video preview file

category: number
in formData

Video category

licence: number
in formData

Video licence

language: string
in formData

Video language

description: string
in formData

Video description

waitTranscoding: boolean
in formData

Whether or not we wait transcoding before publish the video

support: string
in formData

Text describing how to support the video uploader

nsfw: boolean
in formData

Whether or not this video contains sensitive content

name: string
in formData

Video name

tags: string[]
in formData

Video tags

commentsEnabled: boolean
in formData

Enable or disable comments for this video

privacy: string Public, Unlisted
in formData

Video privacy

scheduleUpdate: object
in formData

Schedule an update at a specific datetime

200 OK
VideoUploadResponse

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "video": {
    "id": "number",
    "uuid": "string"
  }
}
OAuth2

Search

The search helps to find videos from within the instance and beyond. Videos from other instances federated by the instance (that is, instances followed by the instance) can be found via keywords and other criteria of the advanced search.

Search

Get the videos corresponding to a given query

GET /search/videos
start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

search: string
in query

String to search

200 OK
Video

successful operation

type
Video
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "uuid": "string",
    "createdAt": "string",
    "publishedAt": "string",
    "updatedAt": "string",
    "category": {
      "id": "number",
      "label": "string"
    },
    "licence": {
      "id": "number",
      "label": "string"
    },
    "language": {
      "id": "string",
      "label": "string"
    },
    "privacy": "string",
    "description": "string",
    "duration": "number",
    "isLocal": "boolean",
    "name": "string",
    "thumbnailPath": "string",
    "previewPath": "string",
    "embedPath": "string",
    "views": "number",
    "likes": "number",
    "dislikes": "number",
    "nsfw": "boolean",
    "account": {
      "name": "string",
      "displayName": "string",
      "url": "string",
      "host": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    }
  }
]

VideoComment

Operations dealing with comments to a video. Comments are organized in threads.

VideoComment

Get the comment threads of a video by its id

GET /videos/{id}/comment-threads
id: string
in path

The video id or uuid

start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
CommentThreadResponse

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "total": "number",
  "data": [
    {
      "id": "number",
      "url": "string",
      "text": "string",
      "threadId": "number",
      "inReplyToCommentId": "number",
      "videoId": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "totalReplies": "number",
      "account": {
        "displayName": "string",
        "id": "number",
        "uuid": "string",
        "url": "string",
        "name": "string",
        "host": "string",
        "followingCount": "number",
        "followersCount": "number",
        "createdAt": "string",
        "updatedAt": "string",
        "avatar": {
          "path": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      }
    }
  ]
}
VideoComment

Creates a comment thread, on a video by its id

POST /videos/{id}/comment-threads
id: string
in path

The video id or uuid

200 OK
CommentThreadPostResponse

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "comment": {
    "id": "number",
    "url": "string",
    "text": "string",
    "threadId": "number",
    "inReplyToCommentId": "number",
    "videoId": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "totalReplies": "number",
    "account": {
      "displayName": "string",
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    }
  }
}
OAuth2
VideoComment

Get the comment thread by its id, of a video by its id

GET /videos/{id}/comment-threads/{threadId}
id: string
in path

The video id or uuid

threadId: number
in path

The thread id (root comment id)

200 OK
VideoCommentThreadTree

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "comment": {
    "id": "number",
    "url": "string",
    "text": "string",
    "threadId": "number",
    "inReplyToCommentId": "number",
    "videoId": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "totalReplies": "number",
    "account": {
      "displayName": "string",
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    }
  },
  "children": [
    {
      "comment": {
        "id": "number",
        "url": "string",
        "text": "string",
        "threadId": "number",
        "inReplyToCommentId": "number",
        "videoId": "number",
        "createdAt": "string",
        "updatedAt": "string",
        "totalReplies": "number",
        "account": {
          "displayName": "string",
          "id": "number",
          "uuid": "string",
          "url": "string",
          "name": "string",
          "host": "string",
          "followingCount": "number",
          "followersCount": "number",
          "createdAt": "string",
          "updatedAt": "string",
          "avatar": {
            "path": "string",
            "createdAt": "string",
            "updatedAt": "string"
          }
        }
      },
      "children": [
        {
          "comment": {
            "id": "number",
            "url": "string",
            "text": "string",
            "threadId": "number",
            "inReplyToCommentId": "number",
            "videoId": "number",
            "createdAt": "string",
            "updatedAt": "string",
            "totalReplies": "number",
            "account": {
              "id": "number",
              "uuid": "string",
              "url": "string",
              "name": "string",
              "host": "string",
              "followingCount": "number",
              "followersCount": "number",
              "createdAt": "string",
              "updatedAt": "string",
              "avatar": {
                "path": "string",
                "createdAt": "string",
                "updatedAt": "string"
              }
            }
          }
        }
      ]
    }
  ]
}
VideoComment

Creates a comment in a comment thread by its id, of a video by its id

POST /videos/{id}/comments/{commentId}
id: string
in path

The video id or uuid

threadId: number
in path

The comment id

200 OK
CommentThreadPostResponse

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "comment": {
    "id": "number",
    "url": "string",
    "text": "string",
    "threadId": "number",
    "inReplyToCommentId": "number",
    "videoId": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "totalReplies": "number",
    "account": {
      "displayName": "string",
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    }
  }
}
OAuth2
VideoComment

Delete a comment in a comment therad by its id, of a video by its id

DELETE /videos/{id}/comments/{commentId}
id: string
in path

The video id or uuid

threadId: number
in path

The comment id

204 No Content

Successful operation

Response Content-Types: application/json
OAuth2

VideoChannel

Operations dealing with creation, modification and video listing of a user's channels.

VideoChannel

Get list of video channels

GET /video-channels
start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
VideoChannel

successful operation

type
VideoChannel
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "displayName": "string",
    "description": "string",
    "isLocal": "boolean",
    "ownerAccount": {
      "id": "number",
      "uuid": "string"
    }
  }
]
VideoChannel

Creates a video channel for the current user

POST /video-channels
VideoChannelInput

undefined

Request Content-Types: application/json
Request Example
{
  "name": "string",
  "description": "string"
}
204 No Content

Successful operation

Response Content-Types: application/json
OAuth2
VideoChannel

Get a video channel by its id

GET /video-channels/{id}
id: string
in path

The video channel id or uuid

200 OK
VideoChannel

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "displayName": "string",
  "description": "string",
  "isLocal": "boolean",
  "ownerAccount": {
    "id": "number",
    "uuid": "string"
  }
}
VideoChannel

Update a video channel by its id

PUT /video-channels/{id}
VideoChannelInput

undefined

id: string
in path

The video channel id or uuid

Request Content-Types: application/json
Request Example
{
  "name": "string",
  "description": "string"
}
204 No Content

Successful operation

Response Content-Types: application/json
OAuth2
VideoChannel

Delete a video channel by its id

DELETE /video-channels/{id}
id: string
in path

The video channel id or uuid

204 No Content

Successful operation

Response Content-Types: application/json
OAuth2
VideoChannel

Get videos of a video channel by its id

GET /video-channels/{id}/videos
id: string
in path

The video channel id or uuid

200 OK
Video

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "number",
  "uuid": "string",
  "createdAt": "string",
  "publishedAt": "string",
  "updatedAt": "string",
  "category": {
    "id": "number",
    "label": "string"
  },
  "licence": {
    "id": "number",
    "label": "string"
  },
  "language": {
    "id": "string",
    "label": "string"
  },
  "privacy": "string",
  "description": "string",
  "duration": "number",
  "isLocal": "boolean",
  "name": "string",
  "thumbnailPath": "string",
  "previewPath": "string",
  "embedPath": "string",
  "views": "number",
  "likes": "number",
  "dislikes": "number",
  "nsfw": "boolean",
  "account": {
    "name": "string",
    "displayName": "string",
    "url": "string",
    "host": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  }
}
VideoChannel

Get video channels of an account by its name

GET /accounts/{name}/video-channels
name: string
in path

The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for example)

200 OK
VideoChannel

successful operation

type
VideoChannel
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "displayName": "string",
    "description": "string",
    "isLocal": "boolean",
    "ownerAccount": {
      "id": "number",
      "uuid": "string"
    }
  }
]

User

User

Creates user

POST /users
AddUser

User to create

Request Content-Types: application/json
Request Example
{
  "username": "string",
  "password": "string",
  "email": "string",
  "videoQuota": "string",
  "role": "string"
}
200 OK
AddUserResponse

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "number",
  "uuid": "string"
}
OAuth2 admin
User

Get a list of users

GET /users
start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
User

successful operation

type
User
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "username": "string",
    "email": "string",
    "displayNSFW": "boolean",
    "autoPlayVideo": "boolean",
    "role": "string",
    "videoQuota": "number",
    "createdAt": "string",
    "account": {
      "displayName": "string",
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    },
    "videoChannels": [
      {
        "displayName": "string",
        "description": "string",
        "isLocal": "boolean",
        "ownerAccount": {
          "id": "number",
          "uuid": "string"
        }
      }
    ]
  }
]
OAuth2
User

Delete a user by its id

DELETE /users/{id}
id: number
in path

The user id

204 No Content

Successful operation

Response Content-Types: application/json
OAuth2 admin
User

Get user by its id

GET /users/{id}
id: number
in path

The user id

200 OK
User

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "number",
  "username": "string",
  "email": "string",
  "displayNSFW": "boolean",
  "autoPlayVideo": "boolean",
  "role": "string",
  "videoQuota": "number",
  "createdAt": "string",
  "account": {
    "displayName": "string",
    "id": "number",
    "uuid": "string",
    "url": "string",
    "name": "string",
    "host": "string",
    "followingCount": "number",
    "followersCount": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  },
  "videoChannels": [
    {
      "displayName": "string",
      "description": "string",
      "isLocal": "boolean",
      "ownerAccount": {
        "id": "number",
        "uuid": "string"
      }
    }
  ]
}
OAuth2
User

Update user profile by its id

PUT /users/{id}
UpdateUser

undefined

id: number
in path

The user id

Request Content-Types: application/json
Request Example
{
  "id": "string",
  "email": "string",
  "videoQuota": "string",
  "role": "string"
}
204 No Content

Successful operation

Response Content-Types: application/json
OAuth2
User

Get current user information

GET /users/me
200 OK
User

successful operation

type
User
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "username": "string",
    "email": "string",
    "displayNSFW": "boolean",
    "autoPlayVideo": "boolean",
    "role": "string",
    "videoQuota": "number",
    "createdAt": "string",
    "account": {
      "displayName": "string",
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    },
    "videoChannels": [
      {
        "displayName": "string",
        "description": "string",
        "isLocal": "boolean",
        "ownerAccount": {
          "id": "number",
          "uuid": "string"
        }
      }
    ]
  }
]
OAuth2
User

Update current user information

PUT /users/me
UpdateMe

undefined

Request Content-Types: application/json
Request Example
{
  "password": "string",
  "email": "string",
  "displayNSFW": "string",
  "autoPlayVideo": "string"
}
204 No Content

Successful operation

Response Content-Types: application/json
OAuth2
User

Get current user used quota

GET /users/me/video-quota-used
200 OK

successful operation

type
number
Response Content-Types: application/json
Response Example (200 OK) 
"number"
OAuth2
User

Get rating of video by its id, among those of the current user

GET /users/me/videos/{videoId}/rating
videoId: string
in path

The video id

200 OK
GetMeVideoRating

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "string",
  "rating": "number"
}
OAuth2
User

Get videos of the current user

GET /users/me/videos
start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
Video

successful operation

type
Video
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "uuid": "string",
    "createdAt": "string",
    "publishedAt": "string",
    "updatedAt": "string",
    "category": {
      "id": "number",
      "label": "string"
    },
    "licence": {
      "id": "number",
      "label": "string"
    },
    "language": {
      "id": "string",
      "label": "string"
    },
    "privacy": "string",
    "description": "string",
    "duration": "number",
    "isLocal": "boolean",
    "name": "string",
    "thumbnailPath": "string",
    "previewPath": "string",
    "embedPath": "string",
    "views": "number",
    "likes": "number",
    "dislikes": "number",
    "nsfw": "boolean",
    "account": {
      "name": "string",
      "displayName": "string",
      "url": "string",
      "host": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    }
  }
]
OAuth2
User

Register a user

POST /users/register
RegisterUser

undefined

Request Content-Types: application/json
Request Example
{
  "username": "string",
  "password": "string",
  "email": "string"
}
204 No Content

Successful operation

Response Content-Types: application/json
User

Update current user avatar

POST /users/me/avatar/pick
avatarfile: file
in formData

The file to upload.

200 OK
Avatar

successful operation

Response Content-Types: application/json
Response Example (200 OK) 
{
  "path": "string",
  "createdAt": "string",
  "updatedAt": "string"
}
OAuth2

VideoBlacklist

VideoBlacklist

Put on blacklist a video by its id

POST /videos/{id}/blacklist
id: string
in path

The video id or uuid

204 No Content

Successful operation

Response Content-Types: application/json
OAuth2 admin, moderator
VideoBlacklist

Delete an entry of the blacklist of a video by its id

DELETE /videos/{id}/blacklist
id: string
in path

The video id or uuid

204 No Content

Successful operation

Response Content-Types: application/json
OAuth2 admin, moderator
VideoBlacklist

Get list of videos on blacklist

GET /videos/blacklist
start: number
in query

Offset

count: number
in query

Number of items

sort: string
in query

Sort column (-createdAt for example)

200 OK
VideoBlacklist

successful operation

type
VideoBlacklist
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "number",
    "videoId": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "name": "string",
    "uuid": "string",
    "description": "string",
    "duration": "number",
    "views": "number",
    "likes": "number",
    "dislikes": "number",
    "nsfw": "boolean"
  }
]
OAuth2 admin, moderator

VideoRate

VideoRate

Vote for a video by its id

PUT /videos/{id}/rate
id: string
in path

The video id or uuid

204 No Content

Successful operation

Response Content-Types: application/json
OAuth2

Schema Definitions

VideoConstantNumber:

id: number
label: string
Example
{
  "id": "number",
  "label": "string"
}

VideoConstantString:

id: string
label: string
Example
{
  "id": "string",
  "label": "string"
}

VideoPrivacy: string

string Public, Unlisted, Private

Video:

id: number
uuid: string
createdAt: string
publishedAt: string
updatedAt: string
category: VideoConstantNumber
licence: VideoConstantNumber
language: VideoConstantString
privacy: VideoPrivacy
description: string
duration: number
isLocal: boolean
name: string
thumbnailPath: string
previewPath: string
embedPath: string
views: number
likes: number
dislikes: number
nsfw: boolean
account: object
name: string
displayName: string
url: string
host: string
avatar: Avatar
Example
{
  "id": "number",
  "uuid": "string",
  "createdAt": "string",
  "publishedAt": "string",
  "updatedAt": "string",
  "category": {
    "id": "number",
    "label": "string"
  },
  "licence": {
    "id": "number",
    "label": "string"
  },
  "language": {
    "id": "string",
    "label": "string"
  },
  "privacy": "string",
  "description": "string",
  "duration": "number",
  "isLocal": "boolean",
  "name": "string",
  "thumbnailPath": "string",
  "previewPath": "string",
  "embedPath": "string",
  "views": "number",
  "likes": "number",
  "dislikes": "number",
  "nsfw": "boolean",
  "account": {
    "name": "string",
    "displayName": "string",
    "url": "string",
    "host": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  }
}

VideoAbuse:

id: number
reason: string
reporterAccount: Account
video: object
id: number
name: string
uuid: string
url: string
createdAt: string
Example
{
  "id": "number",
  "reason": "string",
  "reporterAccount": {
    "displayName": "string",
    "id": "number",
    "uuid": "string",
    "url": "string",
    "name": "string",
    "host": "string",
    "followingCount": "number",
    "followersCount": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  },
  "video": {
    "id": "number",
    "name": "string",
    "uuid": "string",
    "url": "string"
  },
  "createdAt": "string"
}

VideoBlacklist:

id: number
videoId: number
createdAt: string
updatedAt: string
name: string
uuid: string
description: string
duration: number
views: number
likes: number
dislikes: number
nsfw: boolean
Example
{
  "id": "number",
  "videoId": "number",
  "createdAt": "string",
  "updatedAt": "string",
  "name": "string",
  "uuid": "string",
  "description": "string",
  "duration": "number",
  "views": "number",
  "likes": "number",
  "dislikes": "number",
  "nsfw": "boolean"
}

VideoChannel:

displayName: string
description: string
isLocal: boolean
ownerAccount: object
id: number
uuid: string
Example
{
  "displayName": "string",
  "description": "string",
  "isLocal": "boolean",
  "ownerAccount": {
    "id": "number",
    "uuid": "string"
  }
}

VideoComment:

id: number
url: string
text: string
threadId: number
inReplyToCommentId: number
videoId: number
createdAt: string
updatedAt: string
totalReplies: number
account: Account
Example
{
  "id": "number",
  "url": "string",
  "text": "string",
  "threadId": "number",
  "inReplyToCommentId": "number",
  "videoId": "number",
  "createdAt": "string",
  "updatedAt": "string",
  "totalReplies": "number",
  "account": {
    "displayName": "string",
    "id": "number",
    "uuid": "string",
    "url": "string",
    "name": "string",
    "host": "string",
    "followingCount": "number",
    "followersCount": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  }
}

VideoCommentThreadTree:

comment: VideoComment
children: VideoCommentThreadTree
VideoCommentThreadTree
Example
{
  "comment": {
    "id": "number",
    "url": "string",
    "text": "string",
    "threadId": "number",
    "inReplyToCommentId": "number",
    "videoId": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "totalReplies": "number",
    "account": {
      "displayName": "string",
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    }
  },
  "children": [
    {
      "comment": {
        "id": "number",
        "url": "string",
        "text": "string",
        "threadId": "number",
        "inReplyToCommentId": "number",
        "videoId": "number",
        "createdAt": "string",
        "updatedAt": "string",
        "totalReplies": "number",
        "account": {
          "displayName": "string",
          "id": "number",
          "uuid": "string",
          "url": "string",
          "name": "string",
          "host": "string",
          "followingCount": "number",
          "followersCount": "number",
          "createdAt": "string",
          "updatedAt": "string",
          "avatar": {
            "path": "string",
            "createdAt": "string",
            "updatedAt": "string"
          }
        }
      },
      "children": [
        {
          "comment": {
            "id": "number",
            "url": "string",
            "text": "string",
            "threadId": "number",
            "inReplyToCommentId": "number",
            "videoId": "number",
            "createdAt": "string",
            "updatedAt": "string",
            "totalReplies": "number",
            "account": {
              "displayName": "string",
              "id": "number",
              "uuid": "string",
              "url": "string",
              "name": "string",
              "host": "string",
              "followingCount": "number",
              "followersCount": "number",
              "createdAt": "string",
              "updatedAt": "string",
              "avatar": {
                "path": "string",
                "createdAt": "string",
                "updatedAt": "string"
              }
            }
          }
        }
      ]
    }
  ]
}

Avatar:

path: string
createdAt: string
updatedAt: string
Example
{
  "path": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Actor:

id: number
uuid: string
url: string
name: string
host: string
followingCount: number
followersCount: number
createdAt: string
updatedAt: string
avatar: Avatar
Example
{
  "id": "number",
  "uuid": "string",
  "url": "string",
  "name": "string",
  "host": "string",
  "followingCount": "number",
  "followersCount": "number",
  "createdAt": "string",
  "updatedAt": "string",
  "avatar": {
    "path": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Account:

displayName: string
Example
{
  "displayName": "string",
  "id": "number",
  "uuid": "string",
  "url": "string",
  "name": "string",
  "host": "string",
  "followingCount": "number",
  "followersCount": "number",
  "createdAt": "string",
  "updatedAt": "string",
  "avatar": {
    "path": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

User:

id: number
username: string
email: string
displayNSFW: boolean
autoPlayVideo: boolean
role: string User, Moderator, Administrator
videoQuota: number
createdAt: string
account: Account
videoChannels: VideoChannel
VideoChannel
Example
{
  "id": "number",
  "username": "string",
  "email": "string",
  "displayNSFW": "boolean",
  "autoPlayVideo": "boolean",
  "role": "string",
  "videoQuota": "number",
  "createdAt": "string",
  "account": {
    "displayName": "string",
    "id": "number",
    "uuid": "string",
    "url": "string",
    "name": "string",
    "host": "string",
    "followingCount": "number",
    "followersCount": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  },
  "videoChannels": [
    {
      "displayName": "string",
      "description": "string",
      "isLocal": "boolean",
      "ownerAccount": {
        "id": "number",
        "uuid": "string"
      }
    }
  ]
}

ServerConfig:

signup: object
allowed: boolean
transcoding: object
enabledResolutions: number[]
number
avatar: object
file: object
size: object
max: number
extensions: string[]
string
video: object
file: object
extensions: string[]
string
Example
{
  "signup": {
    "allowed": "boolean"
  },
  "transcoding": {
    "enabledResolutions": [
      "number"
    ]
  },
  "avatar": {
    "file": {
      "size": {
        "max": "number"
      }
    },
    "extensions": [
      "string"
    ]
  },
  "video": {
    "file": {
      "extensions": [
        "string"
      ]
    }
  }
}

Follow:

id: number
follower: Actor
following: Actor
score: number
state: string pending, accepted
createdAt: string
updatedAt: string
Example
{
  "id": "number",
  "follower": {
    "id": "number",
    "uuid": "string",
    "url": "string",
    "name": "string",
    "host": "string",
    "followingCount": "number",
    "followersCount": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  },
  "following": {
    "id": "number",
    "uuid": "string",
    "url": "string",
    "name": "string",
    "host": "string",
    "followingCount": "number",
    "followersCount": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "avatar": {
      "path": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  },
  "score": "number",
  "state": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Job:

id: number
state: string pending, processing, error, success
category: string transcoding, activitypub-http
handlerName: string
handlerInputData: string
createdAt: string
updatedAt: string
Example
{
  "id": "number",
  "state": "string",
  "category": "string",
  "handlerName": "string",
  "handlerInputData": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

AddUserResponse:

id: number
uuid: string
Example
{
  "id": "number",
  "uuid": "string"
}

VideoUploadResponse:

video: object
id: number
uuid: string
Example
{
  "video": {
    "id": "number",
    "uuid": "string"
  }
}

CommentThreadResponse:

total: number
data: VideoComment
VideoComment
Example
{
  "total": "number",
  "data": [
    {
      "id": "number",
      "url": "string",
      "text": "string",
      "threadId": "number",
      "inReplyToCommentId": "number",
      "videoId": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "totalReplies": "number",
      "account": {
        "displayName": "string",
        "id": "number",
        "uuid": "string",
        "url": "string",
        "name": "string",
        "host": "string",
        "followingCount": "number",
        "followersCount": "number",
        "createdAt": "string",
        "updatedAt": "string",
        "avatar": {
          "path": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      }
    }
  ]
}

CommentThreadPostResponse:

comment: VideoComment
Example
{
  "comment": {
    "id": "number",
    "url": "string",
    "text": "string",
    "threadId": "number",
    "inReplyToCommentId": "number",
    "videoId": "number",
    "createdAt": "string",
    "updatedAt": "string",
    "totalReplies": "number",
    "account": {
      "displayName": "string",
      "id": "number",
      "uuid": "string",
      "url": "string",
      "name": "string",
      "host": "string",
      "followingCount": "number",
      "followersCount": "number",
      "createdAt": "string",
      "updatedAt": "string",
      "avatar": {
        "path": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    }
  }
}

AddUser:

username: string

The user username

password: string

The user password

email: string

The user email

videoQuota: string

The user videoQuota

role: string

The user role

Example
{
  "username": "string",
  "password": "string",
  "email": "string",
  "videoQuota": "string",
  "role": "string"
}

UpdateUser:

id: string

The user id

email: string

The updated email of the user

videoQuota: string

The updated videoQuota of the user

role: string

The updated role of the user

Example
{
  "id": "string",
  "email": "string",
  "videoQuota": "string",
  "role": "string"
}

UpdateMe:

password: string

Your new password

email: string

Your new email

displayNSFW: string

Your new displayNSFW

autoPlayVideo: string

Your new autoPlayVideo

Example
{
  "password": "string",
  "email": "string",
  "displayNSFW": "string",
  "autoPlayVideo": "string"
}

GetMeVideoRating:

id: string

Id of the video

rating: number

Rating of the video

Example
{
  "id": "string",
  "rating": "number"
}

RegisterUser:

username: string

The username of the user

password: string

The password of the user

email: string

The email of the user

Example
{
  "username": "string",
  "password": "string",
  "email": "string"
}

VideoChannelInput:

name: string
description: string
Example
{
  "name": "string",
  "description": "string"
}
Documentation by Spectacle