canonical: https://jentic.com/apis/cpy.re/peertube

# Cpy Re PeerTube

PeerTube is a free, decentralized, federated video platform built on ActivityPub and WebTorrent, and the PeerTube REST API is its programmatic surface. The API spans 244 endpoints covering video upload and transcoding, channels and playlists, accounts and users, federation between instances, live streaming, comments, abuse reports, and instance administration. Authentication is via OAuth 2.0 access tokens scoped to a single account session, and rate limits are enforced at 50 calls per 10 seconds per endpoint with stricter limits on token and registration endpoints. Client integrations exist in Python, Go, and Kotlin generated from this specification.

## For AI agents

Upload videos, manage channels, run live streams, and moderate accounts on a PeerTube instance. Use when an agent needs to publish or manage video content on a federated, self-hosted alternative to YouTube.

## Scope

Does not handle commercial DRM, ad insertion, or proprietary CDN delivery - use for federated, self-hosted video publishing and management only.

## Capabilities

- Upload videos to a PeerTube channel and trigger transcoding to multiple resolutions
- Create and manage live streams with replay and permanent live options
- Moderate accounts, comments, and abuse reports across a federated instance
- Manage user-facing channels, playlists, and subscriptions
- Federate with other PeerTube instances by following and unfollowing remote actors
- Configure instance-wide settings, plugins, and redundancy strategies

## Use cases

### Automated Video Publishing Pipeline

A media organisation publishes long-form video to its self-hosted PeerTube instance as a YouTube alternative. After rendering, a publishing job calls POST `/api/v1/videos` to upload the file, sets channel, language, tags, and privacy, and PeerTube handles transcoding to multiple resolutions. This avoids vendor lock-in and keeps the content under the publisher's control.

Example prompt: Call POST `/api/v1/videos` with the rendered MP4 file, channelId 42, name 'Weekly Update', and privacy 1 (public), then poll until the transcoding job completes.

### Live Streaming for Events

An events team runs a live stream from a conference using PeerTube live broadcasting. POST `/api/v1/videos/live` creates the live video and returns the RTMP ingestion URL and stream key. After the broadcast, the recording is preserved when saveReplay is enabled, so attendees who missed the event can watch on demand. This is a self-hosted alternative to commercial live platforms.

Example prompt: Create a live video with POST `/api/v1/videos/live` for channelId 7, saveReplay true, then return the rtmpUrl and streamKey to the broadcaster.

### Federation and Content Discovery

An instance administrator follows other PeerTube instances so videos from those servers appear in the local discovery feed. POST `/api/v1/server/following` sends a follow request, and remote videos then federate in via ActivityPub. GET `/api/v1/search/videos` lets users search across the federated network. This is what makes PeerTube a network rather than a single site.

Example prompt: Send POST `/api/v1/server/following` with hosts ['videos.example.org'] to follow the remote instance, then GET `/api/v1/search/videos`?search=climate to confirm federated results appear.

### Comment and Abuse Moderation

A community manager reviews abuse reports filed against videos and comments on the instance. GET `/api/v1/abuses` lists open reports and DELETE `/api/v1/videos/{id}/comment-threads/{threadId}` removes problematic comment threads. This keeps the federated community safer without manually trawling each video page.

Example prompt: List abuses with GET `/api/v1/abuses`?state=pending, and for each video-level abuse, delete the offending comment thread via DELETE `/api/v1/videos/{id}/comment-threads/{threadId}.`

### Agent-Driven Content Operations

An AI content operations agent embedded in a media team's workflow handles end-to-end PeerTube tasks: upload finished renders, write descriptions, schedule premieres, and triage abuse queues. Through Jentic, the agent finds each PeerTube operation by intent and executes it without holding raw OAuth credentials, so the same workflow can run unattended overnight.

Example prompt: Search Jentic for 'upload video to peertube', execute POST `/api/v1/videos` with the rendered file, then POST `/api/v1/video-playlists/{playlistId}/videos` to add it to the weekly playlist.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/videos/upload` | Upload a video file |
| GET | `/api/v1/videos` | List videos on the instance |
| POST | `/api/v1/videos/live` | Create a live video stream |
| GET | `/api/v1/search/videos` | Search videos across the federated network |
| POST | `/api/v1/users/token` | Obtain an OAuth access token |
| GET | `/api/v1/abuses` | List abuse reports for moderation |
| POST | `/api/v1/server/following` | Follow a remote PeerTube instance |

## Key resources

- **Videos** — Upload, list, update, delete, and stream videos and live broadcasts
- **Channels** — Manage channels, their videos, and ownership
- **Accounts** — Manage user accounts, profiles, and roles
- **Playlists** — Create and manage playlists of videos
- **Server Federation** — Follow and unfollow remote PeerTube instances
- **Abuses** — File and moderate abuse reports against content and accounts

## Why Jentic

- **Setup:** Wiring PeerTube by hand means learning its OAuth2 token flow, pointing calls at your chosen federated instance host, and coding your own requests across video upload, live, and moderation endpoints. Through Jentic you install once, import PeerTube from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** PeerTube puts the video and channel ids in the URL path across its video and moderation routes, so a rule can pin your agent to one video or channel: it acts only on that resource. You choose the operations it may call, so state-changing ones like following a server or acting on abuse reports are not included unless you add them.
- **Credential handling:** Your PeerTube credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upload a video' or 'search videos on the instance', and Jentic returns the matching PeerTube operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Vimeo API** — Vimeo is a hosted commercial video platform with similar upload, channel, and live capabilities.
- **api.video** — api.video is a developer-focused video infrastructure API for upload, transcoding, and delivery.
- **Mux API** — Mux provides commercial video streaming infrastructure with on-demand and live capabilities.
- **Cloudinary API** — Cloudinary handles upstream image and video transformation that can feed into a PeerTube pipeline.

## FAQ

### What authentication does the PeerTube API use?

PeerTube uses OAuth 2.0 password grant. Clients obtain an access token via POST `/api/v1/users/token` using the username, password, and client credentials returned by GET `/api/v1/oauth-clients/local.` Only one access token can be used at a time per session. Through Jentic, the credentials are stored encrypted and the token is refreshed automatically.

### Can I upload videos to PeerTube programmatically?

Yes. POST `/api/v1/videos/upload` accepts a multipart upload with the video file, channelId, name, and privacy fields. PeerTube then runs transcoding to produce multiple resolutions; the video appears on the channel once the transcoding job completes.

### What are the rate limits for the PeerTube API?

PeerTube limits all `/api/v1`/* endpoints to 50 calls per 10 seconds by default. POST `/api/v1/users/token` is limited to 15 calls per 5 minutes, POST `/api/v1/users/register` to 2 per 5 minutes, and POST `/api/v1/users/ask-send-verify-email` to 3 per 5 minutes. Instance administrators can override these. A 429 response with Retry-After indicates the limit was reached.

### How do I start a live stream on PeerTube through Jentic?

Search Jentic for 'create live stream on peertube', load the POST `/api/v1/videos/live` schema, and execute with channelId and saveReplay options. The response includes the rtmpUrl and streamKey that the broadcaster sends to from OBS or another encoder.

### Does PeerTube support federation between instances?

Yes. PeerTube federates over ActivityPub. POST `/api/v1/server/following` sends a follow request to a remote instance and DELETE `/api/v1/server/following/{host}` unfollows it. Once federated, remote videos appear in local search and discovery feeds.

### Is PeerTube free to use?

PeerTube itself is free and open-source software released under the AGPL. There is no per-call pricing - costs are limited to whatever hosting and bandwidth you provide for your own instance. Public instances may impose their own quotas.

### Can I limit what my agent is allowed to do with the PeerTube API?

Yes. Because you run Jentic One yourself, your own rules decide which PeerTube operations and credentials the agent may use. Since PeerTube carries the video and channel ids in the URL path across its video and moderation routes, you can pin the agent to a single video or channel so it acts only on that resource. You also choose which operations it may call, so state-changing calls like POST `/api/v1/server/following` to follow a remote instance or acting on abuse reports via GET `/api/v1/abuses` are excluded unless you add them.