# Video

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


## Request video token

`POST /api/v1/videos/{id}/token`

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

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

- `x-peertube-video-password` (header, string, optional) - Required on password protected video
  Type: string

Responses:

- 200: successful operation

Content type: application/json

Type: VideoTokenResponse

Schema: [VideoTokenResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videotokenresponse.md)

- `files` (optional)
  Type: object
  
  - `token` (optional)
    Type: string
  
  - `expires` (optional)
    Type: string, date-time

- 400: incorrect parameters

- 404: video not found

## Examples

### cURL

```bash
curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/token' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://peertube2.cpy.re/api/v1/videos/42/token',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a studio task

`POST /api/v1/videos/{id}/studio/edit`

Create a task to edit a video (cut, add intro/outro etc). By default the video is edited in place. Set `saveAsNewVideo` to keep it untouched and save the result in a new video.

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Request body: multipart/form-data (required)

Type: object

- `tasks` (required)
  Reference: [VideoStudioCreateTask](https://docs.joinpeertube.org/api-rest-reference/api/models/videostudiocreatetask.md); Type: Array<object>

- `saveAsNewVideo` (optional)
  Type: boolean
  
  Keep the source video untouched: duplicate it, and edit the duplicate. The duplicate is created private, in the same channel as the source video, with the source video metadata. The size of the source video counts towards the user quota.
  
  
  default: false

Responses:

- 200: successful operation, when `saveAsNewVideo` is `true`. Returns the identifiers of the new video

Content type: application/json

Type: VideoUploadResponse

Schema: [VideoUploadResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videouploadresponse.md)

- `video` (optional)
  Type: object
  
  - `id` (optional)
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    object id for the video
  
  - `uuid` (optional)
    Type: UUIDv4
    
    universal identifier for the video, that can be used across instances
    
    allOf:
      Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
      
      minLength: 36
      
      maxLength: 36
      
      pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
      
      Example:
      
      ```json
      "9c9de5e8-0a1e-484a-b099-e80766180a6d"
      ```
  
  - `shortUUID` (optional)
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID

- 204: successful operation, when the source video is edited in place

- 400: incorrect parameters

- 403: the user cannot manage this video, or `saveAsNewVideo` is `true` on a blocked video and the user cannot manage blocks

- 404: video not found

- 409: video is already being processed

## Examples

### cURL

```bash
curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/studio/edit' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'tasks={"name":"cut","options":{"start":0,"end":0}}' \
  --form-string 'saveAsNewVideo=false'
```

### JavaScript

```javascript
const form = new FormData();
form.append('tasks', '{"name":"cut","options":{"start":0,"end":0}}');
form.append('saveAsNewVideo', 'false');
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/studio/edit', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());
```

### Python

```python
import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('tasks', (None, '{"name":"cut","options":{"start":0,"end":0}}')),
        ('saveAsNewVideo', (None, 'false')),
    ]
    response = requests.request('POST', 'https://peertube2.cpy.re/api/v1/videos/42/studio/edit', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)
```


## Duplicate a video

`POST /api/v1/videos/{id}/duplicate`

Create a copy of a local video, in the same channel.

The copy of a blocked video (that only moderators can duplicate) is blocked for the same reason.


Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Request body: application/json

Type: object

- `name` (optional)
  Type: string
  
  Name of the copy. Defaults to the name of the source video followed by "(Copy)"
  
  minLength: 3
  
  maxLength: 120

Responses:

- 200: successful operation. Returns the identifiers of the new video

Content type: application/json

Type: VideoUploadResponse

Schema: [VideoUploadResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videouploadresponse.md)

- `video` (optional)
  Type: object
  
  - `id` (optional)
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    object id for the video
  
  - `uuid` (optional)
    Type: UUIDv4
    
    universal identifier for the video, that can be used across instances
    
    allOf:
      Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
      
      minLength: 36
      
      maxLength: 36
      
      pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
      
      Example:
      
      ```json
      "9c9de5e8-0a1e-484a-b099-e80766180a6d"
      ```
  
  - `shortUUID` (optional)
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID

- 400: incorrect parameters

- 403: the user cannot manage this video, the video is not local, or the video is blocked and the user cannot manage blocks

- 404: video not found

- 409: video is already being processed

- 413: the user video quota is exceeded

## Examples

### cURL

```bash
curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/duplicate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/duplicate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string"
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/videos/42/duplicate',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List videos

`GET /api/v1/videos`

Authentication: no security requirement declared for this operation.

Parameters:

- `start` (query, integer, optional) - Offset used to paginate results
  Type: integer
  
  minimum: 0

- `count` (query, integer, optional) - Number of items to return
  Type: integer
  
  default: 15
  
  minimum: 1
  
  maximum: 100

- `skipCount` (query, string, optional) - if you don't need the `total` in the response
  Type: string
  
  default: "false"
  
  enum: ["true","false"]

- `sort` (query, string, optional)
  Type: string
  
  Sort videos by criteria (prefixing with `-` means `DESC` order):
    * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
    * `best` - Same than `hot`, but also takes into account user video history
    * `trending` - Sort videos by recent views ("recent" is defined by the admin)
    * `views` - Sort videos using their `views` counter
    * `publishedAt` - Sort by video publication date (when it became publicly available)
  
  
  enum: ["name","-duration","-createdAt","-publishedAt","-views","-likes","-comments","-trending","-hot","-best"]

- `nsfw` (query, string, optional) - whether to include nsfw videos, if any
  Type: string
  
  enum: ["true","false"]

- `nsfwFlagsIncluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `nsfwFlagsExcluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `aiUsageOneOf` (query, VideoAIUsageSet | Array<VideoAIUsageSet>, optional) - **PeerTube >= 9.0** Only list videos with one of these AI usages, declared by video creators.
If not provided, the preference of the authenticated user (`aiUsagesHidden`) is used

  Type: VideoAIUsageSet | Array<VideoAIUsageSet>
  
  oneOf:
    Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
    
    **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
      - `1` Not specified
      - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
      - `3` Contains AI-generated content: some parts of the video have been generated by AI
      - `4` AI-generated: the whole video, or most of it, has been generated by AI
    
    
    enum: [1,2,3,4]
  
    Type: Array<VideoAIUsageSet>
    
    Items:
      Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
      
      **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
        - `1` Not specified
        - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
        - `3` Contains AI-generated content: some parts of the video have been generated by AI
        - `4` AI-generated: the whole video, or most of it, has been generated by AI
      
      
      enum: [1,2,3,4]

- `isLive` (query, boolean, optional) - whether or not the video is a live
  Type: boolean

- `includeScheduledLive` (query, boolean, optional) - whether or not include live that are scheduled for later
  Type: boolean

- `categoryOneOf` (query, VideoCategorySet | Array<VideoCategorySet>, optional) - category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
  Type: VideoCategorySet | Array<VideoCategorySet>
  
  oneOf:
    Reference: [VideoCategorySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocategoryset.md); Type: VideoCategorySet
    
    category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
    
    Example:
    
    ```json
    15
    ```
  
    Type: Array<VideoCategorySet>
    
    Items:
      Reference: [VideoCategorySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocategoryset.md); Type: VideoCategorySet
      
      category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
      
      Example:
      
      ```json
      15
      ```

- `licenceOneOf` (query, VideoLicenceSet | Array<VideoLicenceSet>, optional) - licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
  Type: VideoLicenceSet | Array<VideoLicenceSet>
  
  oneOf:
    Reference: [VideoLicenceSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolicenceset.md); Type: VideoLicenceSet
    
    licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
    
    Example:
    
    ```json
    2
    ```
  
    Type: Array<VideoLicenceSet>
    
    Items:
      Reference: [VideoLicenceSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolicenceset.md); Type: VideoLicenceSet
      
      licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
      
      Example:
      
      ```json
      2
      ```

- `languageOneOf` (query, VideoLanguageSet | Array<VideoLanguageSet>, optional) - language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html)). Use `_unknown` to filter on videos that don't have a video language
  Type: VideoLanguageSet | Array<VideoLanguageSet>
  
  oneOf:
    Reference: [VideoLanguageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolanguageset.md); Type: VideoLanguageSet
    
    language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html))
    
    Example:
    
    ```json
    "en"
    ```
  
    Type: Array<VideoLanguageSet>
    
    Items:
      Reference: [VideoLanguageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolanguageset.md); Type: VideoLanguageSet
      
      language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html))
      
      Example:
      
      ```json
      "en"
      ```

- `tagsOneOf` (query, string | Array<string>, optional) - tag(s) of the video
  Type: string | Array<string>
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    maxItems: 5
    
    Items:
      Type: string

- `tagsAllOf` (query, string | Array<string>, optional) - tag(s) of the video, where all should be present in the video
  Type: string | Array<string>
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    Items:
      Type: string

- `isLocal` (query, boolean, optional) - **PeerTube >= 4.0** Display only local or remote objects
  Type: boolean

- `include` (query, integer, optional) - **Only administrators and moderators can use this parameter**

Include additional videos in results (can be combined using bitwise or operator)
- `0` NONE
- `1` NOT_PUBLISHED_STATE
- `2` BLACKLISTED
- `4` BLOCKED_OWNER
- `8` FILES
- `16` CAPTIONS
- `32` VIDEO SOURCE

  Type: integer
  
  enum: [0,1,2,4,8,16,32]

- `hasHLSFiles` (query, boolean, optional) - **PeerTube >= 4.0** Display only videos that have HLS files
  Type: boolean

- `hasWebVideoFiles` (query, boolean, optional) - **PeerTube >= 6.0** Display only videos that have Web Video files
  Type: boolean

- `host` (query, string, optional) - Find elements owned by this host
  Type: string

- `autoTagOneOf` (query, string | Array<string>, optional) - **PeerTube >= 6.2** **Admins and moderators only** filter on videos that contain one of these automatic tags
  Type: string | Array<string>
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    Items:
      Type: string

- `stateOneOf` (query, id | Array<id>, optional) - **PeerTube >= 8.2** **Admins and moderators only** filter on videos that have one of these states
  Type: id | Array<id>
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    The video state:
    - `1`: Published
    - `2`: To transcode
    - `3`: To import
    - `4`: Waiting for live stream
    - `5`: Live ended
    - `6`: To move to an external storage (object storage...)
    - `7`: Transcoding failed
    - `8`: Moving to an external storage failed
    - `9`: To edit using studio edition feature
    - `10`: To move to the file system
    - `11`: Moving to the file system failed
    - `12`: Import failed
    - `13`: To duplicate, the files of another video are being copied
    - `14`: Duplication failed, the files of the other video could not be copied
    - `15`: The studio edition of a video saved as a new video failed
    
    
    enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]
  
    Type: Array<id>
    
    Items:
      Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
      
      The video state:
      - `1`: Published
      - `2`: To transcode
      - `3`: To import
      - `4`: Waiting for live stream
      - `5`: Live ended
      - `6`: To move to an external storage (object storage...)
      - `7`: Transcoding failed
      - `8`: Moving to an external storage failed
      - `9`: To edit using studio edition feature
      - `10`: To move to the file system
      - `11`: Moving to the file system failed
      - `12`: Import failed
      - `13`: To duplicate, the files of another video are being copied
      - `14`: Duplication failed, the files of the other video could not be copied
      - `15`: The studio edition of a video saved as a new video failed
      
      
      enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]

- `privacyOneOf` (query, VideoPrivacySet, optional) - **PeerTube >= 4.0** Display only videos in this specific privacy/privacies
  Type: VideoPrivacySet
  
  privacy id of the video (see [/videos/privacies](https://docs.joinpeertube.org/api-rest-reference/api/operations/getvideoprivacypolicies.html))
  
  Schema: [VideoPrivacySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoprivacyset.md)
  
  enum: [1,2,3,4,5]

- `excludeAlreadyWatched` (query, boolean, optional) - Whether or not to exclude videos that are in the user's video history
  Type: boolean

- `search` (query, string, optional) - Plain text search, applied to various parts of the model depending on endpoint
  Type: string

Responses:

- 200: successful operation

Content type: application/json

Type: VideoListResponse

Schema: [VideoListResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videolistresponse.md)

- `total` (optional)
  Type: integer
  
  Example:
  
  ```json
  1
  ```

- `data` (optional)
  Type: Array<Video>
  
  maxItems: 100
  
  Items:
    Reference: [Video](https://docs.joinpeertube.org/api-rest-reference/api/models/video.md); Type: Video

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/videos?count=15&skipCount=false'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos?count=15&skipCount=false', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://peertube2.cpy.re/api/v1/videos?count=15&skipCount=false')
print(response.text)
```


## List recommended videos

`GET /api/v1/recommendations/videos`

Return videos recommended next to a reference video (or general recommendations if no reference video is given).

PeerTube decides the recommendation algorithm: it currently lists videos sharing tags with the reference video
(excluding videos already watched by the authenticated user), then the latest videos.
All returned videos are restricted to the `scope`, which defaults to the `recommendationScope` of the reference video.


Authentication: no security requirement declared for this operation.

Parameters:

- `scope` (query, VideoRecommendationScopeSet, optional) - Restrict recommended videos. Defaults to the `recommendationScope` of the reference video, or to `1` (all videos) if no reference video is given

  Type: VideoRecommendationScopeSet
  
  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
  
  
  Schema: [VideoRecommendationScopeSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videorecommendationscopeset.md)
  
  enum: [1,2,3,4]

- `videoId` (query, id | UUIDv4 | shortUUID, optional) - Reference video. Required if `scope` is `3` or `4`
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

- `count` (query, integer, optional) - Number of videos to return
  Type: integer
  
  default: 10
  
  minimum: 1
  
  maximum: 30

- `excludeVideoIds` (query, Array<id>, optional) - Videos that must not be recommended (the reference video is always excluded)
  Type: Array<id>
  
  maxItems: 50
  
  Items:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```

- `x-peertube-video-password` (header, string, optional) - Required on password protected video
  Type: string

- `nsfw` (query, string, optional) - whether to include nsfw videos, if any
  Type: string
  
  enum: ["true","false"]

- `nsfwFlagsIncluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `nsfwFlagsExcluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `aiUsageOneOf` (query, VideoAIUsageSet | Array<VideoAIUsageSet>, optional) - **PeerTube >= 9.0** Only list videos with one of these AI usages, declared by video creators.
If not provided, the preference of the authenticated user (`aiUsagesHidden`) is used

  Type: VideoAIUsageSet | Array<VideoAIUsageSet>
  
  oneOf:
    Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
    
    **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
      - `1` Not specified
      - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
      - `3` Contains AI-generated content: some parts of the video have been generated by AI
      - `4` AI-generated: the whole video, or most of it, has been generated by AI
    
    
    enum: [1,2,3,4]
  
    Type: Array<VideoAIUsageSet>
    
    Items:
      Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
      
      **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
        - `1` Not specified
        - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
        - `3` Contains AI-generated content: some parts of the video have been generated by AI
        - `4` AI-generated: the whole video, or most of it, has been generated by AI
      
      
      enum: [1,2,3,4]

Responses:

- 200: successful operation

Content type: application/json

Type: VideoListResponse

Schema: [VideoListResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videolistresponse.md)

- `total` (optional)
  Type: integer
  
  Example:
  
  ```json
  1
  ```

- `data` (optional)
  Type: Array<Video>
  
  maxItems: 100
  
  Items:
    Reference: [Video](https://docs.joinpeertube.org/api-rest-reference/api/models/video.md); Type: Video

- 400: invalid parameters or missing `videoId`

- 401: reference video requires authentication or a password

- 403: reference video is not visible by the user or the password is invalid

- 404: reference video not found

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/recommendations/videos?count=10'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/recommendations/videos?count=10', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://peertube2.cpy.re/api/v1/recommendations/videos?count=10')
print(response.text)
```


## List available video categories

`GET /api/v1/videos/categories`

Authentication: no security requirement declared for this operation.

Responses:

- 200: successful operation

Content type: application/json

Type: Array<string>

Items:
  Type: string

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/videos/categories'
```

### JavaScript

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

const data = await response.text();
```

### Python

```python
import requests

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


## List available video licences

`GET /api/v1/videos/licences`

Authentication: no security requirement declared for this operation.

Responses:

- 200: successful operation

Content type: application/json

Type: Array<string>

Items:
  Type: string

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/videos/licences'
```

### JavaScript

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

const data = await response.text();
```

### Python

```python
import requests

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


## List available video languages

`GET /api/v1/videos/languages`

Authentication: no security requirement declared for this operation.

Parameters:

- `scope` (query, string, optional) - **PeerTube >= 8.2** Filter languages by scope. Use `subtitle` to exclude sign languages and other languages that don't make sense for subtitles.
  Type: string
  
  enum: ["subtitle"]

Responses:

- 200: successful operation

Content type: application/json

Type: Array<string>

Items:
  Type: string

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/videos/languages'
```

### JavaScript

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

const data = await response.text();
```

### Python

```python
import requests

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


## List available video privacy policies

`GET /api/v1/videos/privacies`

Authentication: no security requirement declared for this operation.

Responses:

- 200: successful operation

Content type: application/json

Type: Array<string>

Items:
  Type: string

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/videos/privacies'
```

### JavaScript

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

const data = await response.text();
```

### Python

```python
import requests

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


## Get a video

`GET /api/v1/videos/{id}`

Authentication: no security requirement declared for this operation.

Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

- `x-peertube-video-password` (header, string, optional) - Required on password protected video
  Type: string

Responses:

- 200: successful operation

Content type: application/json

Type: Video & object

Schema: [VideoDetails](https://docs.joinpeertube.org/api-rest-reference/api/models/videodetails.md)

allOf:
  Reference: [Video](https://docs.joinpeertube.org/api-rest-reference/api/models/video.md); Type: Video

  Type: object
  
  - `viewers` (optional)
    Type: integer
    
    If the video is a live, you have the amount of current viewers
  
  - `description` (optional)
    Type: string; nullable
    
    full description of the video, written in Markdown.
    
    
    minLength: 3
    
    maxLength: 1000
    
    Example:
    
    ```json
    "\"**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\\r\\n\\r\\n\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\\r\\n*A decentralized video hosting network,\nbased on free/libre software!*\\r\\n\\r\\n**Animation Produced by:** [LILA](https://libreart.info) - [ZeMarmot Team](https://film.zemarmot.net)\\r\\n\n*Directed by* Aryeom\\r\\n*Assistant* Jehan\\r\\n**Licence**: [CC-By-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)\\r\\n\\r\\n\n**Sponsored by** [Framasoft](https://framasoft.org)\\r\\n\\r\\n**Music**: [Red Step Forward](http://play.dogmazic.net/song.php?song_id=52491) - CC-By Ken Bushima\\r\\n\\r\\n\n**Movie Clip**: [Caminades 3: Llamigos](http://www.caminandes.com/) CC-By Blender Institute\\r\\n\\r\\n**Video sources**: https://gitlab.gnome.org/Jehan/what-is-peertube/\"\n"
    ```
  
  - `support` (optional)
    Type: string; nullable
    
    A text tell the audience how to support the video creator
    
    minLength: 3
    
    maxLength: 1000
    
    Example:
    
    ```json
    "Please support our work on https://soutenir.framasoft.org/en/ <3"
    ```
  
  - `channel` (optional)
    Reference: [VideoChannel](https://docs.joinpeertube.org/api-rest-reference/api/models/videochannel.md); Type: Actor & object
  
  - `account` (optional)
    Reference: [Account](https://docs.joinpeertube.org/api-rest-reference/api/models/account.md); Type: Actor & any
  
  - `tags` (optional)
    Type: Array<string>
    
    minItems: 1
    
    maxItems: 5
    
    Example:
    
    ```json
    [
      "flowers",
      "gardening"
    ]
    ```
    
    Items:
      Type: string
      
      minLength: 2
      
      maxLength: 30
  
  - `commentsPolicy` (optional)
    Reference: [VideoCommentsPolicyConstant](https://docs.joinpeertube.org/api-rest-reference/api/models/videocommentspolicyconstant.md); Type: VideoCommentsPolicyConstant
  
  - `downloadEnabled` (optional)
    Type: boolean
  
  - `inputFileUpdatedAt` (optional)
    Type: string, date-time; nullable
    
    Latest input file update. Null if the file has never been replaced since the original upload
  
  - `trackerUrls` (optional)
    Type: Array<string>
    
    WebTorrent (`ws://` or `wss://`) and BitTorrent (`http://` or `https://`) trackers of the video
    
    
    Example:
    
    ```json
    [
      "https://peertube2.cpy.re/tracker/announce",
      "wss://peertube2.cpy.re/tracker/socket"
    ]
    ```
    
    Items:
      Type: string, url
  
  - `files` (optional)
    Type: Array<VideoFile>
    
    Web compatible video files. If Web Video is disabled on the server:
    
    - field will be empty
    - video files will be found in `streamingPlaylists[].files` field
    
    
    Items:
      Reference: [VideoFile](https://docs.joinpeertube.org/api-rest-reference/api/models/videofile.md); Type: VideoFile
  
  - `streamingPlaylists` (optional)
    Type: Array<VideoStreamingPlaylists>
    
    HLS playlists/manifest files. If HLS is disabled on the server:
    
    - field will be empty
    - video files will be found in `files` field
    
    
    Items:
      Reference: [VideoStreamingPlaylists](https://docs.joinpeertube.org/api-rest-reference/api/models/videostreamingplaylists.md); Type: object & VideoStreamingPlaylists-HLS

- 401: Requires authentication or the video requires a password

Content type: application/json

Type: ServerError

Schema: [ServerError](https://docs.joinpeertube.org/api-rest-reference/api/models/servererror.md)

- `type` (optional)
  Type: string, uri-reference
  
  URI identifying the error type. `about:blank` when the error has no specific type. Otherwise it links to the corresponding section of the [Errors](https://docs.joinpeertube.org/api-rest-reference/api.md#errors) documentation; the type name itself is also available in `code`.
  
  
  Example:
  
  ```json
  "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/video_requires_password"
  ```

- `detail` (optional)
  Type: string
  
  Example:
  
  ```json
  "Please provide a password to access this password protected video"
  ```

- `status` (optional)
  Type: integer
  
  Example:
  
  ```json
  403
  ```

- `code` (optional)
  Type: string
  
  Example:
  
  ```json
  "video_requires_password"
  ```

- 403: Invalid authentication or the video requires a password

Content type: application/json

Type: ServerError

Schema: [ServerError](https://docs.joinpeertube.org/api-rest-reference/api/models/servererror.md)

- `type` (optional)
  Type: string, uri-reference
  
  URI identifying the error type. `about:blank` when the error has no specific type. Otherwise it links to the corresponding section of the [Errors](https://docs.joinpeertube.org/api-rest-reference/api.md#errors) documentation; the type name itself is also available in `code`.
  
  
  Example:
  
  ```json
  "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/video_requires_password"
  ```

- `detail` (optional)
  Type: string
  
  Example:
  
  ```json
  "Please provide a password to access this password protected video"
  ```

- `status` (optional)
  Type: integer
  
  Example:
  
  ```json
  403
  ```

- `code` (optional)
  Type: string
  
  Example:
  
  ```json
  "video_requires_password"
  ```

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/videos/42'
```

### JavaScript

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

const data = await response.text();
```

### Python

```python
import requests

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


## Update a video

`PUT /api/v1/videos/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Request body: multipart/form-data

Type: object

- `channelId` (optional)
  Type: integer
  
  New channel of the video. The channel must be owned by the same account as the previous one. Use the "change ownership" endpoints to give a video to a channel owned by another account on the local PeerTube instance.

- `thumbnailfile` (optional)
  Type: string, binary
  
  Video thumbnail file

- `previewfile` (optional)
  Type: string, binary
  
  Deprecated in PeerTube v8.1, use thumbnailfile instead
  
  deprecated: true

- `category` (optional)
  Reference: [VideoCategorySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocategoryset.md); Type: VideoCategorySet
  
  category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
  
  Example:
  
  ```json
  15
  ```

- `licence` (optional)
  Reference: [VideoLicenceSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolicenceset.md); Type: VideoLicenceSet
  
  licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
  
  Example:
  
  ```json
  2
  ```

- `language` (optional)
  Reference: [VideoLanguageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolanguageset.md); Type: VideoLanguageSet
  
  language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html))
  
  Example:
  
  ```json
  "en"
  ```

- `privacy` (optional)
  Reference: [VideoPrivacySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoprivacyset.md); Type: VideoPrivacySet
  
  privacy id of the video (see [/videos/privacies](https://docs.joinpeertube.org/api-rest-reference/api/operations/getvideoprivacypolicies.html))
  
  enum: [1,2,3,4,5]

- `description` (optional)
  Type: string
  
  Video description

- `waitTranscoding` (optional)
  Type: string
  
  Whether or not we wait transcoding before publish the video

- `support` (optional)
  Type: string
  
  A text tell the audience how to support the video creator
  
  Example:
  
  ```json
  "Please support our work on https://soutenir.framasoft.org/en/ <3"
  ```

- `nsfw` (optional)
  Type: boolean
  
  Whether or not this video contains sensitive content

- `nsfwSummary` (optional)
  Type: any
  
  More information about the sensitive content of the video

- `nsfwFlags` (optional)
  Reference: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md); Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  enum: [0,1,2,4]

- `name` (optional)
  Type: string
  
  Video name
  
  minLength: 3
  
  maxLength: 120

- `tags` (optional)
  Type: Array<string>
  
  Video tags (maximum 5 tags each between 2 and 30 characters)
  
  minItems: 1
  
  maxItems: 5
  
  Items:
    Type: string
    
    minLength: 2
    
    maxLength: 30

- `commentsPolicy` (optional)
  Reference: [VideoCommentsPolicySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocommentspolicyset.md); Type: VideoCommentsPolicySet
  
  Comments policy of the video (Enabled = `1`, Disabled = `2`, Requires Approval = `3`)
  
  enum: [1,2,3]

- `recommendationScope` (optional)
  Reference: [VideoRecommendationScopeSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videorecommendationscopeset.md); Type: VideoRecommendationScopeSet
  
  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
  
  
  enum: [1,2,3,4]

- `aiUsage` (optional)
  Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
  
  **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
    - `1` Not specified
    - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
    - `3` Contains AI-generated content: some parts of the video have been generated by AI
    - `4` AI-generated: the whole video, or most of it, has been generated by AI
  
  
  enum: [1,2,3,4]

- `commercialContent` (optional)
  Reference: [VideoCommercialContentSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocommercialcontentset.md); Type: VideoCommercialContentSet
  
  **PeerTube >= 9.0** Commercial content in the video, declared by the video creator:
    - `1` None
    - `2` Promotional content: the creator promotes their own products, services or business
    - `3` Paid partnership: a third party paid, or provided goods or services, in exchange for the promotion
  
  
  enum: [1,2,3]

- `downloadEnabled` (optional)
  Type: boolean
  
  Enable or disable downloading for this video

- `originallyPublishedAt` (optional)
  Type: string, date-time; nullable
  
  Date when the content was originally published

- `scheduleUpdate` (optional)
  Reference: [VideoScheduledUpdate](https://docs.joinpeertube.org/api-rest-reference/api/models/videoscheduledupdate.md); Type: VideoScheduledUpdate

- `videoPasswords` (optional)
  Reference: [AddVideoPasswords](https://docs.joinpeertube.org/api-rest-reference/api/models/addvideopasswords.md); Type: Array<password>
  
  uniqueItems: true

Responses:

- 204: successful operation

## Examples

### cURL

```bash
curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/42' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'channelId=0' \
  --form-string 'category=15' \
  --form-string 'licence=2' \
  --form-string 'language=en' \
  --form-string 'privacy=1' \
  --form-string 'description=string' \
  --form-string 'waitTranscoding=string' \
  --form-string 'support=Please support our work on https://soutenir.framasoft.org/en/ <3' \
  --form-string 'nsfw=true' \
  --form-string 'nsfwFlags=0' \
  --form-string 'name=string' \
  --form-string 'tags=string' \
  --form-string 'commentsPolicy=1' \
  --form-string 'recommendationScope=1' \
  --form-string 'aiUsage=1' \
  --form-string 'commercialContent=1' \
  --form-string 'downloadEnabled=true' \
  --form-string 'originallyPublishedAt=2024-01-15T09:30:00Z' \
  --form-string 'scheduleUpdate={"privacy":1,"updateAt":"2024-01-15T09:30:00Z"}' \
  --form-string 'videoPasswords=string'
```

### JavaScript

```javascript
const form = new FormData();
form.append('channelId', '0');
form.append('category', '15');
form.append('licence', '2');
form.append('language', 'en');
form.append('privacy', '1');
form.append('description', 'string');
form.append('waitTranscoding', 'string');
form.append('support', 'Please support our work on https://soutenir.framasoft.org/en/ <3');
form.append('nsfw', 'true');
form.append('nsfwFlags', '0');
form.append('name', 'string');
form.append('tags', 'string');
form.append('commentsPolicy', '1');
form.append('recommendationScope', '1');
form.append('aiUsage', '1');
form.append('commercialContent', '1');
form.append('downloadEnabled', 'true');
form.append('originallyPublishedAt', '2024-01-15T09:30:00Z');
form.append('scheduleUpdate', '{"privacy":1,"updateAt":"2024-01-15T09:30:00Z"}');
form.append('videoPasswords', 'string');
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42', {
  method: 'PUT',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());
```

### Python

```python
import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('channelId', (None, '0')),
        ('category', (None, '15')),
        ('licence', (None, '2')),
        ('language', (None, 'en')),
        ('privacy', (None, '1')),
        ('description', (None, 'string')),
        ('waitTranscoding', (None, 'string')),
        ('support', (None, 'Please support our work on https://soutenir.framasoft.org/en/ <3')),
        ('nsfw', (None, 'true')),
        ('nsfwFlags', (None, '0')),
        ('name', (None, 'string')),
        ('tags', (None, 'string')),
        ('commentsPolicy', (None, '1')),
        ('recommendationScope', (None, '1')),
        ('aiUsage', (None, '1')),
        ('commercialContent', (None, '1')),
        ('downloadEnabled', (None, 'true')),
        ('originallyPublishedAt', (None, '2024-01-15T09:30:00Z')),
        ('scheduleUpdate', (None, '{"privacy":1,"updateAt":"2024-01-15T09:30:00Z"}')),
        ('videoPasswords', (None, 'string')),
    ]
    response = requests.request('PUT', 'https://peertube2.cpy.re/api/v1/videos/42', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)
```


## Delete a video

`DELETE /api/v1/videos/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Responses:

- 204: successful operation

## Examples

### cURL

```bash
curl -X DELETE 'https://peertube2.cpy.re/api/v1/videos/42' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

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

const data = await response.text();
```

### Python

```python
import requests

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


## Notify user is watching a video

`POST /api/v1/videos/{id}/views`

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.

Authentication: no security requirement declared for this operation.

Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Request body: application/json (required)

Type: UserViewingVideo

Schema: [UserViewingVideo](https://docs.joinpeertube.org/api-rest-reference/api/models/userviewingvideo.md)

- `currentTime` (required)
  Type: integer, seconds
  
  timestamp within the video, in seconds
  
  Example:
  
  ```json
  5
  ```

- `viewEvent` (optional)
  Type: string
  
  Event since last viewing call:
   * `seek` - If the user seeked the video
  
  
  enum: ["seek"]

- `sessionId` (optional)
  Type: string
  
  Optional param to represent the current viewer session. Used by the backend to properly count one view per session per video. PeerTube admin can configure the server to not trust this `sessionId` parameter but use the request IP address instead to identify a viewer.
  

- `client` (optional)
  Type: string
  
  Client software used to watch the video. For example "Firefox", "PeerTube Approval Android", etc.
  

- `device` (optional)
  Type: VideoStatsUserAgentDevice
  
  Device used to watch the video. For example "desktop", "mobile", "smarttv", etc.
  
  
  allOf:
    Reference: [VideoStatsUserAgentDevice](https://docs.joinpeertube.org/api-rest-reference/api/models/videostatsuseragentdevice.md); Type: VideoStatsUserAgentDevice
    
    enum: ["console","embedded","mobile","smarttv","tablet","wearable","xr","desktop"]

- `operatingSystem` (optional)
  Type: string
  
  Operating system used to watch the video. For example "Windows", "Ubuntu", etc.
  

Responses:

- 204: successful operation

## Examples

### cURL

```bash
curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/views' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "currentTime": 5,
  "viewEvent": "seek",
  "sessionId": "string",
  "client": "string",
  "operatingSystem": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "currentTime": 5,
  "viewEvent": "seek",
  "sessionId": "string",
  "client": "string",
  "operatingSystem": "string"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/views', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "currentTime": 5,
  "viewEvent": "seek",
  "sessionId": "string",
  "client": "string",
  "operatingSystem": "string"
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/videos/42/views',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Upload a video

`POST /api/v1/videos/upload`

Uses a single request to upload a video.

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Request body: multipart/form-data

Type: VideoUploadRequestCommon & object

Schema: [VideoUploadRequestLegacy](https://docs.joinpeertube.org/api-rest-reference/api/models/videouploadrequestlegacy.md)

allOf:
  Reference: [VideoUploadRequestCommon](https://docs.joinpeertube.org/api-rest-reference/api/models/videouploadrequestcommon.md); Type: VideoUploadRequestCommon

  Type: object
  
  - `videofile` (required)
    Type: string, binary
    
    Video file

Responses:

- 200: successful operation

Content type: application/json

Type: VideoUploadResponse

Schema: [VideoUploadResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videouploadresponse.md)

- `video` (optional)
  Type: object
  
  - `id` (optional)
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    object id for the video
  
  - `uuid` (optional)
    Type: UUIDv4
    
    universal identifier for the video, that can be used across instances
    
    allOf:
      Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
      
      minLength: 36
      
      maxLength: 36
      
      pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
      
      Example:
      
      ```json
      "9c9de5e8-0a1e-484a-b099-e80766180a6d"
      ```
  
  - `shortUUID` (optional)
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID

- 403: video didn't pass upload filter

- 408: upload has timed out

- 413: If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `code`:
- `quota_reached` for quota limits whether daily or global


- 415: video type unsupported

- 422: video unreadable

## Examples

### Shell

```Shell
## DEPENDENCIES: jq
USERNAME="<your_username>"
PASSWORD="<your_password>"
FILE_PATH="<your_file_path>"
CHANNEL_ID="<your_channel_id>"
NAME="<video_name>"
API="https://peertube2.cpy.re/api/v1"

## AUTH
client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
token=$(curl -s "$API/users/token" \
  --data client_id="$client_id" \
  --data client_secret="$client_secret" \
  --data grant_type=password \
  --data username="$USERNAME" \
  --data password="$PASSWORD" \
  | jq -r ".access_token")

## VIDEO UPLOAD
curl -s "$API/videos/upload" \
  -H "Authorization: Bearer $token" \
  --max-time 600 \
  --form videofile=@"$FILE_PATH" \
  --form channelId=$CHANNEL_ID \
  --form name="$NAME"
```


## Initialize the resumable upload of a video

`POST /api/v1/videos/upload-resumable`

Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `X-Upload-Content-Length` (header, number, required) - Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
  Type: number
  
  Example:
  
  ```json
  2469036
  ```

- `X-Upload-Content-Type` (header, string, mimetype, required) - MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
  Type: string, mimetype
  
  Example:
  
  ```json
  "video/mp4"
  ```

Request body: application/json

Type: VideoUploadRequestCommon & object

Schema: [VideoUploadRequestResumable](https://docs.joinpeertube.org/api-rest-reference/api/models/videouploadrequestresumable.md)

allOf:
  Reference: [VideoUploadRequestCommon](https://docs.joinpeertube.org/api-rest-reference/api/models/videouploadrequestcommon.md); Type: VideoUploadRequestCommon

  Type: object
  
  - `filename` (required)
    Type: string, filename
    
    Video filename including extension
    
    Example:
    
    ```json
    "what_is_peertube.mp4"
    ```
  
  - `thumbnailfile` (optional)
    Type: string, binary
    
    Video thumbnail file
  
  - `previewfile` (optional)
    Type: string, binary
    
    Deprecated in PeerTube v8.1, use thumbnailfile instead
    
    deprecated: true

Responses:

- 200: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead

- 201: created

- 413: Disambiguate via `code`:
- `max_file_size_reached` for the absolute file size limit
- `quota_reached` for quota limits whether daily or global


- 415: video type unsupported

## Examples

### cURL

```bash
curl -X POST 'https://peertube2.cpy.re/api/v1/videos/upload-resumable' \
  -H 'X-Upload-Content-Length: 2469036' \
  -H 'X-Upload-Content-Type: video/mp4' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "What is PeerTube?",
  "channelId": 3,
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\\r\\n\\r\\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\n",
  "waitTranscoding": true,
  "generateTranscription": true,
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "tags": [
    "framasoft",
    "peertube"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "videoPasswords": [
    "string"
  ],
  "filename": "what_is_peertube.mp4"
}'
```

### JavaScript

```javascript
const body = `{
  "name": "What is PeerTube?",
  "channelId": 3,
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\\\\r\\\\n\\\\r\\\\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\\n",
  "waitTranscoding": true,
  "generateTranscription": true,
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "tags": [
    "framasoft",
    "peertube"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "videoPasswords": [
    "string"
  ],
  "filename": "what_is_peertube.mp4"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/upload-resumable', {
  method: 'POST',
  headers: {
    'X-Upload-Content-Length': '2469036',
    'X-Upload-Content-Type': 'video/mp4',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "What is PeerTube?",
  "channelId": 3,
  "privacy": 1,
  "category": 15,
  "licence": 2,
  "language": "en",
  "description": "**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\\\\r\\\\n\\\\r\\\\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\\n",
  "waitTranscoding": true,
  "generateTranscription": true,
  "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  "nsfw": true,
  "nsfwFlags": 0,
  "tags": [
    "framasoft",
    "peertube"
  ],
  "commentsPolicy": 1,
  "recommendationScope": 1,
  "aiUsage": 1,
  "commercialContent": 1,
  "downloadEnabled": true,
  "originallyPublishedAt": "2024-01-15T09:30:00Z",
  "scheduleUpdate": {
    "privacy": 1,
    "updateAt": "2024-01-15T09:30:00Z"
  },
  "thumbnailfile": "<binary>",
  "previewfile": "<binary>",
  "videoPasswords": [
    "string"
  ],
  "filename": "what_is_peertube.mp4"
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/videos/upload-resumable',
    data=body.encode('utf-8'),
    headers={
        'X-Upload-Content-Length': '2469036',
        'X-Upload-Content-Type': 'video/mp4',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Send chunk for the resumable upload of a video

`PUT /api/v1/videos/upload-resumable`

Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `upload_id` (query, string, required) - Created session id to proceed with. If you didn't send chunks in the last hour, it is
not valid anymore and you need to initialize a new upload.

  Type: string

- `Content-Range` (header, string, required) - Specifies the bytes in the file that the request is uploading.

For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
262144 bytes (256 x 1024) in a 2,469,036 byte file.

When the server config `client.videos.resumableUpload.minChunkSize` (video uploads) or
`import.users.resumableUpload.minChunkSize` (user archive imports) is not `0`,
every chunk except the last one must be at least that big. It must also be at least 1/10,000 of the file size
(the maximum number of object storage multipart upload parts).

  Type: string
  
  Example:
  
  ```json
  "bytes 0-262143/2469036"
  ```

- `Content-Length` (header, number, required) - Size of the chunk that the request is sending.

Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1048576 bytes (~1MB) and increases or reduces size depending on connection health.

  Type: number
  
  Example:
  
  ```json
  262144
  ```

Request body: application/octet-stream

Type: string, binary

Responses:

- 200: last chunk received

Content type: application/json

Type: VideoUploadResponse

Schema: [VideoUploadResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videouploadresponse.md)

- `video` (optional)
  Type: object
  
  - `id` (optional)
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    object id for the video
  
  - `uuid` (optional)
    Type: UUIDv4
    
    universal identifier for the video, that can be used across instances
    
    allOf:
      Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
      
      minLength: 36
      
      maxLength: 36
      
      pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
      
      Example:
      
      ```json
      "9c9de5e8-0a1e-484a-b099-e80766180a6d"
      ```
  
  - `shortUUID` (optional)
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID

- 308: resume incomplete

- 400: chunk is smaller than `client.videos.resumableUpload.minChunkSize` of the server config or 1/10,000 of the file size (and is not the last one)

- 403: video didn't pass upload filter

- 404: upload not found

- 409: chunk doesn't match range

- 422: video unreadable

- 429: too many concurrent requests

- 503: upload is already being processed

## Examples

### cURL

```bash
curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string' \
  -H 'Content-Range: bytes 0-262143/2469036' \
  -H 'Content-Length: 262144' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string', {
  method: 'PUT',
  headers: {
    'Content-Range': 'bytes 0-262143/2469036',
    'Content-Length': '262144',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.put(
    'https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string',
    headers={
        'Content-Range': 'bytes 0-262143/2469036',
        'Content-Length': '262144',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Cancel the resumable upload of a video, deleting any data uploaded so far

`DELETE /api/v1/videos/upload-resumable`

Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `upload_id` (query, string, required) - Created session id to proceed with. If you didn't send chunks in the last hour, it is
not valid anymore and you need to initialize a new upload.

  Type: string

- `Content-Length` (header, number, required)
  Type: number
  
  Example:
  
  ```json
  0
  ```

Responses:

- 204: upload cancelled

- 404: upload not found

## Examples

### cURL

```bash
curl -X DELETE 'https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string' \
  -H 'Content-Length: 0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string', {
  method: 'DELETE',
  headers: {
    'Content-Length': '0',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/videos/upload-resumable?upload_id=string',
    headers={
        'Content-Length': '0',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a live

`POST /api/v1/videos/live`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Request body: multipart/form-data

Type: object

- `channelId` (required)
  Type: integer
  
  Channel id that will contain this live video

- `saveReplay` (optional)
  Type: boolean

- `replaySettings` (optional)
  Reference: [LiveVideoReplaySettings](https://docs.joinpeertube.org/api-rest-reference/api/models/livevideoreplaysettings.md); Type: LiveVideoReplaySettings

- `permanentLive` (optional)
  Type: boolean
  
  User can stream multiple times in a permanent live

- `latencyMode` (optional)
  Type: LiveVideoLatencyMode
  
  User can select live latency mode if enabled by the instance
  
  allOf:
    Reference: [LiveVideoLatencyMode](https://docs.joinpeertube.org/api-rest-reference/api/models/livevideolatencymode.md); Type: LiveVideoLatencyMode
    
    The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)
    
    enum: [1,2,3]

- `thumbnailfile` (optional)
  Type: string, binary
  
  Live video/replay thumbnail file

- `previewfile` (optional)
  Type: string, binary
  
  Deprecated in PeerTube v8.1, use thumbnailfile instead
  
  deprecated: true

- `privacy` (optional)
  Reference: [VideoPrivacySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoprivacyset.md); Type: VideoPrivacySet
  
  privacy id of the video (see [/videos/privacies](https://docs.joinpeertube.org/api-rest-reference/api/operations/getvideoprivacypolicies.html))
  
  enum: [1,2,3,4,5]

- `category` (optional)
  Reference: [VideoCategorySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocategoryset.md); Type: VideoCategorySet
  
  category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
  
  Example:
  
  ```json
  15
  ```

- `licence` (optional)
  Reference: [VideoLicenceSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolicenceset.md); Type: VideoLicenceSet
  
  licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
  
  Example:
  
  ```json
  2
  ```

- `language` (optional)
  Reference: [VideoLanguageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolanguageset.md); Type: VideoLanguageSet
  
  language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html))
  
  Example:
  
  ```json
  "en"
  ```

- `description` (optional)
  Type: string
  
  Live video/replay description

- `support` (optional)
  Type: string
  
  A text tell the audience how to support the creator
  
  Example:
  
  ```json
  "Please support our work on https://soutenir.framasoft.org/en/ <3"
  ```

- `nsfw` (optional)
  Type: boolean
  
  Whether or not this live video/replay contains sensitive content

- `nsfwSummary` (optional)
  Type: any
  
  More information about the sensitive content of the video

- `nsfwFlags` (optional)
  Reference: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md); Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  enum: [0,1,2,4]

- `name` (required)
  Type: string
  
  Live video/replay name
  
  minLength: 3
  
  maxLength: 120

- `tags` (optional)
  Type: Array<string>
  
  Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
  
  minItems: 1
  
  maxItems: 5
  
  Items:
    Type: string
    
    minLength: 2
    
    maxLength: 30

- `commentsPolicy` (optional)
  Reference: [VideoCommentsPolicySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocommentspolicyset.md); Type: VideoCommentsPolicySet
  
  Comments policy of the video (Enabled = `1`, Disabled = `2`, Requires Approval = `3`)
  
  enum: [1,2,3]

- `recommendationScope` (optional)
  Reference: [VideoRecommendationScopeSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videorecommendationscopeset.md); Type: VideoRecommendationScopeSet
  
  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
  
  
  enum: [1,2,3,4]

- `aiUsage` (optional)
  Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
  
  **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
    - `1` Not specified
    - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
    - `3` Contains AI-generated content: some parts of the video have been generated by AI
    - `4` AI-generated: the whole video, or most of it, has been generated by AI
  
  
  enum: [1,2,3,4]

- `commercialContent` (optional)
  Reference: [VideoCommercialContentSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocommercialcontentset.md); Type: VideoCommercialContentSet
  
  **PeerTube >= 9.0** Commercial content in the video, declared by the video creator:
    - `1` None
    - `2` Promotional content: the creator promotes their own products, services or business
    - `3` Paid partnership: a third party paid, or provided goods or services, in exchange for the promotion
  
  
  enum: [1,2,3]

- `downloadEnabled` (optional)
  Type: boolean
  
  Enable or disable downloading for the replay of this live video

- `schedules` (optional)
  Type: Array<LiveSchedule>
  
  Items:
    Reference: [LiveSchedule](https://docs.joinpeertube.org/api-rest-reference/api/models/liveschedule.md); Type: LiveSchedule

Responses:

- 200: successful operation

Content type: application/json

Type: VideoUploadResponse

Schema: [VideoUploadResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videouploadresponse.md)

- `video` (optional)
  Type: object
  
  - `id` (optional)
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    object id for the video
  
  - `uuid` (optional)
    Type: UUIDv4
    
    universal identifier for the video, that can be used across instances
    
    allOf:
      Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
      
      minLength: 36
      
      maxLength: 36
      
      pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
      
      Example:
      
      ```json
      "9c9de5e8-0a1e-484a-b099-e80766180a6d"
      ```
  
  - `shortUUID` (optional)
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID

- 400: Disambiguate via `code`:
- default type for a validation error
- `live_conflicting_permanent_and_save_replay` for conflicting parameters set


- 403: Disambiguate via `code`:
- `live_not_enabled` for a disabled live feature
- `live_not_allowing_replay` for a disabled replay feature
- `max_instance_lives_limit_reached` for the absolute concurrent live limit
- `max_user_lives_limit_reached` for the user concurrent live limit


## Examples

### cURL

```bash
curl -X POST 'https://peertube2.cpy.re/api/v1/videos/live' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'channelId=0' \
  --form-string 'saveReplay=true' \
  --form-string 'replaySettings={"privacy":1}' \
  --form-string 'permanentLive=true' \
  --form-string 'privacy=1' \
  --form-string 'category=15' \
  --form-string 'licence=2' \
  --form-string 'language=en' \
  --form-string 'description=string' \
  --form-string 'support=Please support our work on https://soutenir.framasoft.org/en/ <3' \
  --form-string 'nsfw=true' \
  --form-string 'nsfwFlags=0' \
  --form-string 'name=string' \
  --form-string 'tags=string' \
  --form-string 'commentsPolicy=1' \
  --form-string 'recommendationScope=1' \
  --form-string 'aiUsage=1' \
  --form-string 'commercialContent=1' \
  --form-string 'downloadEnabled=true' \
  --form-string 'schedules={"startAt":"2024-01-15T09:30:00Z"}'
```

### JavaScript

```javascript
const form = new FormData();
form.append('channelId', '0');
form.append('saveReplay', 'true');
form.append('replaySettings', '{"privacy":1}');
form.append('permanentLive', 'true');
form.append('privacy', '1');
form.append('category', '15');
form.append('licence', '2');
form.append('language', 'en');
form.append('description', 'string');
form.append('support', 'Please support our work on https://soutenir.framasoft.org/en/ <3');
form.append('nsfw', 'true');
form.append('nsfwFlags', '0');
form.append('name', 'string');
form.append('tags', 'string');
form.append('commentsPolicy', '1');
form.append('recommendationScope', '1');
form.append('aiUsage', '1');
form.append('commercialContent', '1');
form.append('downloadEnabled', 'true');
form.append('schedules', '{"startAt":"2024-01-15T09:30:00Z"}');
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/live', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());
```

### Python

```python
import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('channelId', (None, '0')),
        ('saveReplay', (None, 'true')),
        ('replaySettings', (None, '{"privacy":1}')),
        ('permanentLive', (None, 'true')),
        ('privacy', (None, '1')),
        ('category', (None, '15')),
        ('licence', (None, '2')),
        ('language', (None, 'en')),
        ('description', (None, 'string')),
        ('support', (None, 'Please support our work on https://soutenir.framasoft.org/en/ <3')),
        ('nsfw', (None, 'true')),
        ('nsfwFlags', (None, '0')),
        ('name', (None, 'string')),
        ('tags', (None, 'string')),
        ('commentsPolicy', (None, '1')),
        ('recommendationScope', (None, '1')),
        ('aiUsage', (None, '1')),
        ('commercialContent', (None, '1')),
        ('downloadEnabled', (None, 'true')),
        ('schedules', (None, '{"startAt":"2024-01-15T09:30:00Z"}')),
    ]
    response = requests.request('POST', 'https://peertube2.cpy.re/api/v1/videos/live', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)
```


## Get information about a live

`GET /api/v1/videos/live/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Responses:

- 200: successful operation

Content type: application/json

Type: LiveVideoResponse

Schema: [LiveVideoResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/livevideoresponse.md)

- `rtmpUrl` (optional)
  Type: string
  
  Included in the response if an appropriate token is provided

- `rtmpsUrl` (optional)
  Type: string
  
  Included in the response if an appropriate token is provided

- `streamKey` (optional)
  Type: string
  
  RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided

- `saveReplay` (optional)
  Type: boolean

- `replaySettings` (optional)
  Reference: [LiveVideoReplaySettings](https://docs.joinpeertube.org/api-rest-reference/api/models/livevideoreplaysettings.md); Type: LiveVideoReplaySettings

- `permanentLive` (optional)
  Type: boolean
  
  User can stream multiple times in a permanent live

- `latencyMode` (optional)
  Type: LiveVideoLatencyMode
  
  User can select live latency mode if enabled by the instance
  
  allOf:
    Reference: [LiveVideoLatencyMode](https://docs.joinpeertube.org/api-rest-reference/api/models/livevideolatencymode.md); Type: LiveVideoLatencyMode
    
    The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)
    
    enum: [1,2,3]

- `schedules` (optional)
  Type: Array<LiveSchedule>
  
  Items:
    Reference: [LiveSchedule](https://docs.joinpeertube.org/api-rest-reference/api/models/liveschedule.md); Type: LiveSchedule

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/videos/live/42' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/live/42', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

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


## Update information about a live

`PUT /api/v1/videos/live/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Request body: application/json

Type: LiveVideoUpdate

Schema: [LiveVideoUpdate](https://docs.joinpeertube.org/api-rest-reference/api/models/livevideoupdate.md)

- `saveReplay` (optional)
  Type: boolean

- `replaySettings` (optional)
  Reference: [LiveVideoReplaySettings](https://docs.joinpeertube.org/api-rest-reference/api/models/livevideoreplaysettings.md); Type: LiveVideoReplaySettings

- `permanentLive` (optional)
  Type: boolean
  
  User can stream multiple times in a permanent live

- `latencyMode` (optional)
  Type: LiveVideoLatencyMode
  
  User can select live latency mode if enabled by the instance
  
  allOf:
    Reference: [LiveVideoLatencyMode](https://docs.joinpeertube.org/api-rest-reference/api/models/livevideolatencymode.md); Type: LiveVideoLatencyMode
    
    The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)
    
    enum: [1,2,3]

- `schedules` (optional)
  Type: Array<LiveSchedule>
  
  Items:
    Reference: [LiveSchedule](https://docs.joinpeertube.org/api-rest-reference/api/models/liveschedule.md); Type: LiveSchedule

Responses:

- 204: successful operation

- 400: bad parameters or trying to update a live that has already started

- 403: trying to save replay of the live but saving replay is not enabled on the instance

## Examples

### cURL

```bash
curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/live/42' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "saveReplay": true,
  "replaySettings": {
    "privacy": 1
  },
  "permanentLive": true,
  "schedules": [
    {
      "startAt": "2024-01-15T09:30:00Z"
    }
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "saveReplay": true,
  "replaySettings": {
    "privacy": 1
  },
  "permanentLive": true,
  "schedules": [
    {
      "startAt": "2024-01-15T09:30:00Z"
    }
  ]
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/live/42', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "saveReplay": true,
  "replaySettings": {
    "privacy": 1
  },
  "permanentLive": true,
  "schedules": [
    {
      "startAt": "2024-01-15T09:30:00Z"
    }
  ]
}'''

response = requests.put(
    'https://peertube2.cpy.re/api/v1/videos/live/42',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get video source file metadata

`GET /api/v1/videos/{id}/source`

Get metadata and download link of original video file

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Responses:

- 200: successful operation

Content type: application/json

Type: VideoSource

Schema: [VideoSource](https://docs.joinpeertube.org/api-rest-reference/api/models/videosource.md)

- `inputFilename` (optional)
  Type: string
  
  Uploaded/imported filename

- `fileDownloadUrl` (optional)
  Type: string
  
  **PeerTube >= 6.1** If enabled by the admin, the video source file is kept on the server and can be downloaded by the owner

- `resolution` (optional)
  Type: VideoResolutionConstant
  
  **PeerTube >= 6.1**
  
  allOf:
    Reference: [VideoResolutionConstant](https://docs.joinpeertube.org/api-rest-reference/api/models/videoresolutionconstant.md); Type: VideoResolutionConstant
    
    resolutions and their labels for the video

- `size` (optional)
  Type: integer
  
  **PeerTube >= 6.1** Video file size in bytes

- `fps` (optional)
  Type: number
  
  **PeerTube >= 6.1** Frames per second of the video file

- `width` (optional)
  Type: integer
  
  **PeerTube >= 6.1** Video stream width

- `height` (optional)
  Type: integer
  
  **PeerTube >= 6.1** Video stream height

- `createdAt` (optional)
  Type: string, date-time

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/videos/42/source' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/source', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

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


## Delete video source file

`DELETE /api/v1/videos/{id}/source/file`

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": [
      "admin",
      "moderator"
    ]
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started
; scopes: admin, moderator

Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Responses:

- 204: successful operation

- 404: video source not found

## Examples

### cURL

```bash
curl -X DELETE 'https://peertube2.cpy.re/api/v1/videos/42/source/file' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/source/file', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/videos/42/source/file',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Initialize the resumable replacement of a video

`POST /api/v1/videos/{id}/source/replace-resumable`

**PeerTube >= 6.0** Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the replacement of a video

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

- `X-Upload-Content-Length` (header, number, required) - Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
  Type: number
  
  Example:
  
  ```json
  2469036
  ```

- `X-Upload-Content-Type` (header, string, mimetype, required) - MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
  Type: string, mimetype
  
  Example:
  
  ```json
  "video/mp4"
  ```

Request body: application/json

Type: VideoReplaceSourceRequestResumable

Schema: [VideoReplaceSourceRequestResumable](https://docs.joinpeertube.org/api-rest-reference/api/models/videoreplacesourcerequestresumable.md)

- `filename` (optional)
  Type: string, filename
  
  Video filename including extension
  
  Example:
  
  ```json
  "what_is_peertube.mp4"
  ```

Responses:

- 200: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead

- 201: created

- 413: Disambiguate via `code`:
- `max_file_size_reached` for the absolute file size limit
- `quota_reached` for quota limits whether daily or global


- 415: video type unsupported

## Examples

### cURL

```bash
curl -X POST 'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable' \
  -H 'X-Upload-Content-Length: 2469036' \
  -H 'X-Upload-Content-Type: video/mp4' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "filename": "what_is_peertube.mp4"
}'
```

### JavaScript

```javascript
const body = `{
  "filename": "what_is_peertube.mp4"
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable', {
  method: 'POST',
  headers: {
    'X-Upload-Content-Length': '2469036',
    'X-Upload-Content-Type': 'video/mp4',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "filename": "what_is_peertube.mp4"
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable',
    data=body.encode('utf-8'),
    headers={
        'X-Upload-Content-Length': '2469036',
        'X-Upload-Content-Type': 'video/mp4',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Send chunk for the resumable replacement of a video

`PUT /api/v1/videos/{id}/source/replace-resumable`

**PeerTube >= 6.0** Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the replacement of a video

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

- `upload_id` (query, string, required) - Created session id to proceed with. If you didn't send chunks in the last hour, it is
not valid anymore and you need to initialize a new upload.

  Type: string

- `Content-Range` (header, string, required) - Specifies the bytes in the file that the request is uploading.

For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
262144 bytes (256 x 1024) in a 2,469,036 byte file.

When the server config `client.videos.resumableUpload.minChunkSize` (video uploads) or
`import.users.resumableUpload.minChunkSize` (user archive imports) is not `0`,
every chunk except the last one must be at least that big. It must also be at least 1/10,000 of the file size
(the maximum number of object storage multipart upload parts).

  Type: string
  
  Example:
  
  ```json
  "bytes 0-262143/2469036"
  ```

- `Content-Length` (header, number, required) - Size of the chunk that the request is sending.

Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1048576 bytes (~1MB) and increases or reduces size depending on connection health.

  Type: number
  
  Example:
  
  ```json
  262144
  ```

Request body: application/octet-stream

Type: string, binary

Responses:

- 204: last chunk received: successful operation

- 308: resume incomplete

- 400: chunk is smaller than `client.videos.resumableUpload.minChunkSize` of the server config or 1/10,000 of the file size (and is not the last one)

- 403: video didn't pass file replacement filter

- 404: replace upload not found

- 409: chunk doesn't match range

- 422: video unreadable

- 429: too many concurrent requests

- 503: upload is already being processed

## Examples

### cURL

```bash
curl -X PUT 'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string' \
  -H 'Content-Range: bytes 0-262143/2469036' \
  -H 'Content-Length: 262144' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string', {
  method: 'PUT',
  headers: {
    'Content-Range': 'bytes 0-262143/2469036',
    'Content-Length': '262144',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.put(
    'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string',
    headers={
        'Content-Range': 'bytes 0-262143/2469036',
        'Content-Length': '262144',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Cancel the resumable replacement of a video

`DELETE /api/v1/videos/{id}/source/replace-resumable`

**PeerTube >= 6.0** Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the replacement of a video

Authentication (security requirement alternatives):

```json
[
  {
    "OAuth2": []
  }
]
```

- OAuth2: oauth2. 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__.

[Generate]: https://docs.joinpeertube.org/api/rest-getting-started


Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

- `upload_id` (query, string, required) - Created session id to proceed with. If you didn't send chunks in the last hour, it is
not valid anymore and you need to initialize a new upload.

  Type: string

- `Content-Length` (header, number, required)
  Type: number
  
  Example:
  
  ```json
  0
  ```

Responses:

- 204: source file replacement cancelled

- 404: source file replacement not found

## Examples

### cURL

```bash
curl -X DELETE 'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string' \
  -H 'Content-Length: 0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string', {
  method: 'DELETE',
  headers: {
    'Content-Length': '0',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/videos/42/source/replace-resumable?upload_id=string',
    headers={
        'Content-Length': '0',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List storyboards of a video

`GET /api/v1/videos/{id}/storyboards`

**PeerTube >= 6.0**

Authentication: no security requirement declared for this operation.

Parameters:

- `id` (path, id | UUIDv4 | shortUUID, required) - The object id, uuid or short uuid
  Type: id | UUIDv4 | shortUUID
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    minimum: 1
    
    Example:
    
    ```json
    42
    ```
  
    Reference: [UUIDv4](https://docs.joinpeertube.org/api-rest-reference/api/models/uuidv4.md); Type: UUIDv4, uuid
    
    minLength: 36
    
    maxLength: 36
    
    pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    
    Example:
    
    ```json
    "9c9de5e8-0a1e-484a-b099-e80766180a6d"
    ```
  
    Reference: [shortUUID](https://docs.joinpeertube.org/api-rest-reference/api/models/shortuuid.md); Type: shortUUID
    
    translation of a uuid v4 with a bigger alphabet to have a shorter uuid
    
    Example:
    
    ```json
    "2y84q2MQUMWPbiEcxNXMgC"
    ```

Responses:

- 200: successful operation

Content type: application/json

Type: object

- `storyboards` (optional)
  Type: Array<Storyboard>
  
  Items:
    Reference: [Storyboard](https://docs.joinpeertube.org/api-rest-reference/api/models/storyboard.md); Type: Storyboard

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/videos/42/storyboards'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/videos/42/storyboards', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://peertube2.cpy.re/api/v1/videos/42/storyboards')
print(response.text)
```


## List videos of a video channel

`GET /api/v1/video-channels/{channelHandle}/videos`

Authentication: no security requirement declared for this operation.

Parameters:

- `channelHandle` (path, string, required) - The video channel handle
  Type: string
  
  Example:
  
  ```json
  "my_username | my_username@example.com"
  ```

- `start` (query, integer, optional) - Offset used to paginate results
  Type: integer
  
  minimum: 0

- `count` (query, integer, optional) - Number of items to return
  Type: integer
  
  default: 15
  
  minimum: 1
  
  maximum: 100

- `skipCount` (query, string, optional) - if you don't need the `total` in the response
  Type: string
  
  default: "false"
  
  enum: ["true","false"]

- `sort` (query, string, optional)
  Type: string
  
  Sort videos by criteria (prefixing with `-` means `DESC` order):
    * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
    * `best` - Same than `hot`, but also takes into account user video history
    * `trending` - Sort videos by recent views ("recent" is defined by the admin)
    * `views` - Sort videos using their `views` counter
    * `publishedAt` - Sort by video publication date (when it became publicly available)
  
  
  enum: ["name","-duration","-createdAt","-publishedAt","-views","-likes","-comments","-trending","-hot","-best"]

- `nsfw` (query, string, optional) - whether to include nsfw videos, if any
  Type: string
  
  enum: ["true","false"]

- `nsfwFlagsIncluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `nsfwFlagsExcluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `aiUsageOneOf` (query, VideoAIUsageSet | Array<VideoAIUsageSet>, optional) - **PeerTube >= 9.0** Only list videos with one of these AI usages, declared by video creators.
If not provided, the preference of the authenticated user (`aiUsagesHidden`) is used

  Type: VideoAIUsageSet | Array<VideoAIUsageSet>
  
  oneOf:
    Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
    
    **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
      - `1` Not specified
      - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
      - `3` Contains AI-generated content: some parts of the video have been generated by AI
      - `4` AI-generated: the whole video, or most of it, has been generated by AI
    
    
    enum: [1,2,3,4]
  
    Type: Array<VideoAIUsageSet>
    
    Items:
      Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
      
      **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
        - `1` Not specified
        - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
        - `3` Contains AI-generated content: some parts of the video have been generated by AI
        - `4` AI-generated: the whole video, or most of it, has been generated by AI
      
      
      enum: [1,2,3,4]

- `isLive` (query, boolean, optional) - whether or not the video is a live
  Type: boolean

- `includeScheduledLive` (query, boolean, optional) - whether or not include live that are scheduled for later
  Type: boolean

- `categoryOneOf` (query, VideoCategorySet | Array<VideoCategorySet>, optional) - category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
  Type: VideoCategorySet | Array<VideoCategorySet>
  
  oneOf:
    Reference: [VideoCategorySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocategoryset.md); Type: VideoCategorySet
    
    category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
    
    Example:
    
    ```json
    15
    ```
  
    Type: Array<VideoCategorySet>
    
    Items:
      Reference: [VideoCategorySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocategoryset.md); Type: VideoCategorySet
      
      category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
      
      Example:
      
      ```json
      15
      ```

- `licenceOneOf` (query, VideoLicenceSet | Array<VideoLicenceSet>, optional) - licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
  Type: VideoLicenceSet | Array<VideoLicenceSet>
  
  oneOf:
    Reference: [VideoLicenceSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolicenceset.md); Type: VideoLicenceSet
    
    licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
    
    Example:
    
    ```json
    2
    ```
  
    Type: Array<VideoLicenceSet>
    
    Items:
      Reference: [VideoLicenceSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolicenceset.md); Type: VideoLicenceSet
      
      licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
      
      Example:
      
      ```json
      2
      ```

- `languageOneOf` (query, VideoLanguageSet | Array<VideoLanguageSet>, optional) - language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html)). Use `_unknown` to filter on videos that don't have a video language
  Type: VideoLanguageSet | Array<VideoLanguageSet>
  
  oneOf:
    Reference: [VideoLanguageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolanguageset.md); Type: VideoLanguageSet
    
    language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html))
    
    Example:
    
    ```json
    "en"
    ```
  
    Type: Array<VideoLanguageSet>
    
    Items:
      Reference: [VideoLanguageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolanguageset.md); Type: VideoLanguageSet
      
      language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html))
      
      Example:
      
      ```json
      "en"
      ```

- `tagsOneOf` (query, string | Array<string>, optional) - tag(s) of the video
  Type: string | Array<string>
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    maxItems: 5
    
    Items:
      Type: string

- `tagsAllOf` (query, string | Array<string>, optional) - tag(s) of the video, where all should be present in the video
  Type: string | Array<string>
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    Items:
      Type: string

- `isLocal` (query, boolean, optional) - **PeerTube >= 4.0** Display only local or remote objects
  Type: boolean

- `include` (query, integer, optional) - **Only administrators and moderators can use this parameter**

Include additional videos in results (can be combined using bitwise or operator)
- `0` NONE
- `1` NOT_PUBLISHED_STATE
- `2` BLACKLISTED
- `4` BLOCKED_OWNER
- `8` FILES
- `16` CAPTIONS
- `32` VIDEO SOURCE

  Type: integer
  
  enum: [0,1,2,4,8,16,32]

- `hasHLSFiles` (query, boolean, optional) - **PeerTube >= 4.0** Display only videos that have HLS files
  Type: boolean

- `hasWebVideoFiles` (query, boolean, optional) - **PeerTube >= 6.0** Display only videos that have Web Video files
  Type: boolean

- `host` (query, string, optional) - Find elements owned by this host
  Type: string

- `autoTagOneOf` (query, string | Array<string>, optional) - **PeerTube >= 6.2** **Admins and moderators only** filter on videos that contain one of these automatic tags
  Type: string | Array<string>
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    Items:
      Type: string

- `stateOneOf` (query, id | Array<id>, optional) - **PeerTube >= 8.2** **Admins and moderators only** filter on videos that have one of these states
  Type: id | Array<id>
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    The video state:
    - `1`: Published
    - `2`: To transcode
    - `3`: To import
    - `4`: Waiting for live stream
    - `5`: Live ended
    - `6`: To move to an external storage (object storage...)
    - `7`: Transcoding failed
    - `8`: Moving to an external storage failed
    - `9`: To edit using studio edition feature
    - `10`: To move to the file system
    - `11`: Moving to the file system failed
    - `12`: Import failed
    - `13`: To duplicate, the files of another video are being copied
    - `14`: Duplication failed, the files of the other video could not be copied
    - `15`: The studio edition of a video saved as a new video failed
    
    
    enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]
  
    Type: Array<id>
    
    Items:
      Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
      
      The video state:
      - `1`: Published
      - `2`: To transcode
      - `3`: To import
      - `4`: Waiting for live stream
      - `5`: Live ended
      - `6`: To move to an external storage (object storage...)
      - `7`: Transcoding failed
      - `8`: Moving to an external storage failed
      - `9`: To edit using studio edition feature
      - `10`: To move to the file system
      - `11`: Moving to the file system failed
      - `12`: Import failed
      - `13`: To duplicate, the files of another video are being copied
      - `14`: Duplication failed, the files of the other video could not be copied
      - `15`: The studio edition of a video saved as a new video failed
      
      
      enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]

- `privacyOneOf` (query, VideoPrivacySet, optional) - **PeerTube >= 4.0** Display only videos in this specific privacy/privacies
  Type: VideoPrivacySet
  
  privacy id of the video (see [/videos/privacies](https://docs.joinpeertube.org/api-rest-reference/api/operations/getvideoprivacypolicies.html))
  
  Schema: [VideoPrivacySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoprivacyset.md)
  
  enum: [1,2,3,4,5]

- `excludeAlreadyWatched` (query, boolean, optional) - Whether or not to exclude videos that are in the user's video history
  Type: boolean

- `search` (query, string, optional) - Plain text search, applied to various parts of the model depending on endpoint
  Type: string

Responses:

- 200: successful operation

Content type: application/json

Type: VideoListResponse

Schema: [VideoListResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videolistresponse.md)

- `total` (optional)
  Type: integer
  
  Example:
  
  ```json
  1
  ```

- `data` (optional)
  Type: Array<Video>
  
  maxItems: 100
  
  Items:
    Reference: [Video](https://docs.joinpeertube.org/api-rest-reference/api/models/video.md); Type: Video

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/video-channels/my_username%20%7C%20my_username%40example.com/videos?count=15&skipCount=false'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/video-channels/my_username%20%7C%20my_username%40example.com/videos?count=15&skipCount=false', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://peertube2.cpy.re/api/v1/video-channels/my_username%20%7C%20my_username%40example.com/videos?count=15&skipCount=false')
print(response.text)
```


## Search videos

`GET /api/v1/search/videos`

Authentication: no security requirement declared for this operation.

Parameters:

- `search` (query, string, required) - String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete video information and interact with it.

  Type: string

- `uuids` (query, any, optional) - Find elements with specific UUIDs
  Type: any
  
  Items:
    Type: string

- `searchTarget` (query, string, optional) - If the administrator enabled search index support, you can override the default search target.

**Warning**: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
  * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
  then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
  After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
  * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch
  the data from the origin instance API

  Type: string
  
  enum: ["local","search-index"]

- `start` (query, integer, optional) - Offset used to paginate results
  Type: integer
  
  minimum: 0

- `count` (query, integer, optional) - Number of items to return
  Type: integer
  
  default: 15
  
  minimum: 1
  
  maximum: 100

- `skipCount` (query, string, optional) - if you don't need the `total` in the response
  Type: string
  
  default: "false"
  
  enum: ["true","false"]

- `sort` (query, string, optional)
  Type: string
  
  Sort videos by criteria (prefixing with `-` means `DESC` order):
    * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
    * `best` - Same than `hot`, but also takes into account user video history
    * `trending` - Sort videos by recent views ("recent" is defined by the admin)
    * `views` - Sort videos using their `views` counter
    * `publishedAt` - Sort by video publication date (when it became publicly available)
  
  
  enum: ["name","-duration","-createdAt","-publishedAt","-views","-likes","-comments","-trending","-hot","-best"]

- `nsfw` (query, string, optional) - whether to include nsfw videos, if any
  Type: string
  
  enum: ["true","false"]

- `nsfwFlagsIncluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `nsfwFlagsExcluded` (query, NSFWFlag, optional)
  Type: NSFWFlag
  
  
  NSFW flags (can be combined using bitwise or operator)
  - `0` NONE
  - `1` VIOLENT
  - `2` EXPLICIT_SEX
  
  
  Schema: [NSFWFlag](https://docs.joinpeertube.org/api-rest-reference/api/models/nsfwflag.md)
  
  enum: [0,1,2,4]

- `aiUsageOneOf` (query, VideoAIUsageSet | Array<VideoAIUsageSet>, optional) - **PeerTube >= 9.0** Only list videos with one of these AI usages, declared by video creators.
If not provided, the preference of the authenticated user (`aiUsagesHidden`) is used

  Type: VideoAIUsageSet | Array<VideoAIUsageSet>
  
  oneOf:
    Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
    
    **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
      - `1` Not specified
      - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
      - `3` Contains AI-generated content: some parts of the video have been generated by AI
      - `4` AI-generated: the whole video, or most of it, has been generated by AI
    
    
    enum: [1,2,3,4]
  
    Type: Array<VideoAIUsageSet>
    
    Items:
      Reference: [VideoAIUsageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoaiusageset.md); Type: VideoAIUsageSet
      
      **PeerTube >= 9.0** Use of AI in the video, declared by the video creator:
        - `1` Not specified
        - `2` No AI-generated content: nothing seen or heard in the video has been generated by AI
        - `3` Contains AI-generated content: some parts of the video have been generated by AI
        - `4` AI-generated: the whole video, or most of it, has been generated by AI
      
      
      enum: [1,2,3,4]

- `isLive` (query, boolean, optional) - whether or not the video is a live
  Type: boolean

- `includeScheduledLive` (query, boolean, optional) - whether or not include live that are scheduled for later
  Type: boolean

- `categoryOneOf` (query, VideoCategorySet | Array<VideoCategorySet>, optional) - category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
  Type: VideoCategorySet | Array<VideoCategorySet>
  
  oneOf:
    Reference: [VideoCategorySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocategoryset.md); Type: VideoCategorySet
    
    category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
    
    Example:
    
    ```json
    15
    ```
  
    Type: Array<VideoCategorySet>
    
    Items:
      Reference: [VideoCategorySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videocategoryset.md); Type: VideoCategorySet
      
      category id of the video (see [/videos/categories](https://docs.joinpeertube.org/api-rest-reference/api/operations/getcategories.html))
      
      Example:
      
      ```json
      15
      ```

- `licenceOneOf` (query, VideoLicenceSet | Array<VideoLicenceSet>, optional) - licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
  Type: VideoLicenceSet | Array<VideoLicenceSet>
  
  oneOf:
    Reference: [VideoLicenceSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolicenceset.md); Type: VideoLicenceSet
    
    licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
    
    Example:
    
    ```json
    2
    ```
  
    Type: Array<VideoLicenceSet>
    
    Items:
      Reference: [VideoLicenceSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolicenceset.md); Type: VideoLicenceSet
      
      licence id of the video (see [/videos/licences](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlicences.html))
      
      Example:
      
      ```json
      2
      ```

- `languageOneOf` (query, VideoLanguageSet | Array<VideoLanguageSet>, optional) - language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html)). Use `_unknown` to filter on videos that don't have a video language
  Type: VideoLanguageSet | Array<VideoLanguageSet>
  
  oneOf:
    Reference: [VideoLanguageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolanguageset.md); Type: VideoLanguageSet
    
    language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html))
    
    Example:
    
    ```json
    "en"
    ```
  
    Type: Array<VideoLanguageSet>
    
    Items:
      Reference: [VideoLanguageSet](https://docs.joinpeertube.org/api-rest-reference/api/models/videolanguageset.md); Type: VideoLanguageSet
      
      language id of the video (see [/videos/languages](https://docs.joinpeertube.org/api-rest-reference/api/operations/getlanguages.html))
      
      Example:
      
      ```json
      "en"
      ```

- `tagsOneOf` (query, string | Array<string>, optional) - tag(s) of the video
  Type: string | Array<string>
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    maxItems: 5
    
    Items:
      Type: string

- `tagsAllOf` (query, string | Array<string>, optional) - tag(s) of the video, where all should be present in the video
  Type: string | Array<string>
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    Items:
      Type: string

- `isLocal` (query, boolean, optional) - **PeerTube >= 4.0** Display only local or remote objects
  Type: boolean

- `include` (query, integer, optional) - **Only administrators and moderators can use this parameter**

Include additional videos in results (can be combined using bitwise or operator)
- `0` NONE
- `1` NOT_PUBLISHED_STATE
- `2` BLACKLISTED
- `4` BLOCKED_OWNER
- `8` FILES
- `16` CAPTIONS
- `32` VIDEO SOURCE

  Type: integer
  
  enum: [0,1,2,4,8,16,32]

- `hasHLSFiles` (query, boolean, optional) - **PeerTube >= 4.0** Display only videos that have HLS files
  Type: boolean

- `hasWebVideoFiles` (query, boolean, optional) - **PeerTube >= 6.0** Display only videos that have Web Video files
  Type: boolean

- `host` (query, string, optional) - Find elements owned by this host
  Type: string

- `autoTagOneOf` (query, string | Array<string>, optional) - **PeerTube >= 6.2** **Admins and moderators only** filter on videos that contain one of these automatic tags
  Type: string | Array<string>
  
  oneOf:
    Type: string
  
    Type: Array<string>
    
    Items:
      Type: string

- `stateOneOf` (query, id | Array<id>, optional) - **PeerTube >= 8.2** **Admins and moderators only** filter on videos that have one of these states
  Type: id | Array<id>
  
  oneOf:
    Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
    
    The video state:
    - `1`: Published
    - `2`: To transcode
    - `3`: To import
    - `4`: Waiting for live stream
    - `5`: Live ended
    - `6`: To move to an external storage (object storage...)
    - `7`: Transcoding failed
    - `8`: Moving to an external storage failed
    - `9`: To edit using studio edition feature
    - `10`: To move to the file system
    - `11`: Moving to the file system failed
    - `12`: Import failed
    - `13`: To duplicate, the files of another video are being copied
    - `14`: Duplication failed, the files of the other video could not be copied
    - `15`: The studio edition of a video saved as a new video failed
    
    
    enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]
  
    Type: Array<id>
    
    Items:
      Reference: [id](https://docs.joinpeertube.org/api-rest-reference/api/models/id.md); Type: id
      
      The video state:
      - `1`: Published
      - `2`: To transcode
      - `3`: To import
      - `4`: Waiting for live stream
      - `5`: Live ended
      - `6`: To move to an external storage (object storage...)
      - `7`: Transcoding failed
      - `8`: Moving to an external storage failed
      - `9`: To edit using studio edition feature
      - `10`: To move to the file system
      - `11`: Moving to the file system failed
      - `12`: Import failed
      - `13`: To duplicate, the files of another video are being copied
      - `14`: Duplication failed, the files of the other video could not be copied
      - `15`: The studio edition of a video saved as a new video failed
      
      
      enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]

- `privacyOneOf` (query, VideoPrivacySet, optional) - **PeerTube >= 4.0** Display only videos in this specific privacy/privacies
  Type: VideoPrivacySet
  
  privacy id of the video (see [/videos/privacies](https://docs.joinpeertube.org/api-rest-reference/api/operations/getvideoprivacypolicies.html))
  
  Schema: [VideoPrivacySet](https://docs.joinpeertube.org/api-rest-reference/api/models/videoprivacyset.md)
  
  enum: [1,2,3,4,5]

- `excludeAlreadyWatched` (query, boolean, optional) - Whether or not to exclude videos that are in the user's video history
  Type: boolean

- `startDate` (query, string, date-time, optional) - Get videos that are published after this date
  Type: string, date-time

- `endDate` (query, string, date-time, optional) - Get videos that are published before this date
  Type: string, date-time

- `originallyPublishedStartDate` (query, string, date-time, optional) - Get videos that are originally published after this date
  Type: string, date-time

- `originallyPublishedEndDate` (query, string, date-time, optional) - Get videos that are originally published before this date
  Type: string, date-time

- `durationMin` (query, integer, optional) - Get videos that have this minimum duration
  Type: integer

- `durationMax` (query, integer, optional) - Get videos that have this maximum duration
  Type: integer

Responses:

- 200: successful operation

Content type: application/json

Type: VideoListResponse

Schema: [VideoListResponse](https://docs.joinpeertube.org/api-rest-reference/api/models/videolistresponse.md)

- `total` (optional)
  Type: integer
  
  Example:
  
  ```json
  1
  ```

- `data` (optional)
  Type: Array<Video>
  
  maxItems: 100
  
  Items:
    Reference: [Video](https://docs.joinpeertube.org/api-rest-reference/api/models/video.md); Type: Video

- 500: search index unavailable

## Examples

### cURL

```bash
curl -X GET 'https://peertube2.cpy.re/api/v1/search/videos?search=string&count=15&skipCount=false'
```

### JavaScript

```javascript
const response = await fetch('https://peertube2.cpy.re/api/v1/search/videos?search=string&count=15&skipCount=false', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://peertube2.cpy.re/api/v1/search/videos?search=string&count=15&skipCount=false')
print(response.text)
```