API Reference

This document lists the available API endpoints for VideoCMS.

Authentication Methods

VideoCMS supports two methods of authentication. In both cases, the token/key must be sent in the Authorization header.

1. JWT (Session-based)

Obtained via /api/auth/login. Best for frontend applications and short-lived sessions. Authorization: Bearer <jwt_token>

2. API Keys (Permanent/Long-lived)

Generated by users in their settings. API keys are always prefixed with ak_ for identification. Authorization: Bearer ak_your_api_key

Note: API Keys cannot be used to access Admin-only routes or modify account security settings (like passwords).

Public Web & Player

These routes are primarily used by the video player and public interfaces.

Captcha

• GET /captcha/challenge: Get a captcha challenge.
• POST /captcha/verify: Verify a captcha response.

Player & Streaming

• GET /v/:UUID: Player page for a video.
• GET /:UUID/stream/muted/master.m3u8: Get muted master playlist.
• GET /:UUID/stream/multi/master.m3u8: Get multi-quality master playlist.
• GET /:UUID/image/thumb/:FILE: Get video thumbnail.
• GET /:UUID/:SUBUUID/subtitle/:FILE: Get subtitle file.
• GET /:UUID/:AUDIOUUID/stream/master.m3u8: Get audio stream.
• GET /:UUID/:QUALITY/download/video.mkv: Download video.
• GET /:UUID/:QUALITY/:STREAM/stream/video.mp4: Stream video file directly.
• GET /:UUID/:QUALITY/:FILE: Get video segment/file.
• GET /:UUID/:AUDIOUUID/audio/:FILE: Get audio segment/file.

Except for thumbnails, media routes require the vc_media HttpOnly cookie that is set by visiting the player page at /v/:UUID. Stream tokens are no longer passed in query strings.

Authentication API

Base URL: /api/auth

• POST /login: Login to the system.
• GET /check: Check current authentication status.
• GET /refresh: Refresh authentication token.

Public API

Base URL: /api

• GET /config: Get public configuration.
• GET /file/example: Get an example file.
• GET /p/pages: List public web pages.
• GET /p/page: Get a specific public web page.

Private API (Authenticated)

These routes require a valid JWT token or API Key.

Base URL: /api

API Key Management

These routes allow users to manage their permanent access keys. They require a valid JWT.

• GET /apikeys: List your API keys (Shows prefix and last used time).
• POST /apikey: Generate a new API key. The full key is shown only once.
• DELETE /apikey/:id: Revoke an API key and delete its audit logs.
• GET /apikey/:id/audit: Retrieve the last 100 requests made with a specific key.

UI Navigation

You can find the API key management tools at the following path:

• Navigation: Settings (gear icon) -> API Management tab.
• URL: /my/settings

Folders

• GET /folders: List folders.
• POST /folder: Create a new folder.
• PUT /folder: Update a folder.
• DELETE /folder: Delete a folder.
• DELETE /folders: Bulk delete folders.

Files

• GET /files: List files.
• GET /file: Get file details.
• POST /file: Create a file entry.
• POST /file/upload: Direct single-request file upload.
• POST /file/clone: Clone a file.
• PUT /file: Update file details.
• DELETE /file: Delete a file.
• DELETE /files: Bulk delete files.
• GET /files/search: Search for files.

Tags

• POST /file/tag: Add a tag to a file.
• DELETE /file/tag: Remove a tag from a file.

Uploads (tus)

VideoCMS embeds a tus resumable upload endpoint. All tus requests except OPTIONS require the normal Authorization: Bearer <token> header.

• OPTIONS /uploads: Discover tus protocol support.
• POST /uploads: Create a tus upload. Metadata should include filename; dashboard uploads also send client_upload_uuid and optional parent_folder_id.
• HEAD /uploads/:upload_id: Read current upload offset.
• PATCH /uploads/:upload_id: Upload bytes using Content-Type: application/offset+octet-stream.
• DELETE /uploads/:upload_id: Cancel and remove an unfinished upload.
• GET /uploads/sessions: List active resumable upload sessions.
• POST /uploads/:upload_id/finalize: Import a completed tus upload into VideoCMS and return the created link.

Remote Downloads

Remote downloads are enabled by default globally and per user. They accept HTTP/HTTPS URLs only, block unsafe private/internal network targets, and use the normal video import validation after the file is downloaded.

Statuses: pending, downloading, importing, completed, failed, canceling, canceled.

• POST /remote/download: Create one or more remote download tasks.
• GET /remote/downloads: List your remote downloads. Supports status, limit, and offset.
• POST /remote/download/:id/cancel: Cancel a pending/running remote download.
• POST /remote/download/:id/retry: Retry a failed/canceled remote download.
• DELETE /remote/download/:id: Remove a completed/failed/canceled remote download row.
• DELETE /remote/downloads: Clear terminal remote download rows by status.
• GET /account/remote-download: Get remote download traffic stats.
• GET /account/remote-download/duration: Get remote download duration stats.
• GET /account/remote-download/top: Get top remote download stats.

Account Stats

• GET /account: Get account details.
• GET /account/settings: Get user settings.
• PUT /account/settings: Update user settings.
• GET /account/traffic: Get traffic statistics.
• GET /account/traffic/top: Get top traffic statistics.
• GET /account/upload: Get upload statistics.
• GET /account/upload/top: Get top upload statistics.
• GET /account/encoding: Get encoding statistics.
• GET /account/encoding/top: Get top encoding statistics.
• GET /account/storage/top: Get top storage statistics.

Webhooks

• GET /webhooks: List webhooks.
• POST /webhook: Create a webhook.
• PUT /webhook: Update a webhook.
• DELETE /webhook: Delete a webhook.

Encodings

• GET /encodings: List encoding jobs.

Admin API (Authenticated & Admin)

Base URL: /api

System Stats

• GET /stats: Get system statistics.
• GET /stats/traffic: Get global traffic stats.
• GET /stats/traffic/top: Get global top traffic stats.
• GET /stats/upload: Get global upload stats.
• GET /stats/upload/top: Get global top upload stats.
• GET /stats/encoding: Get global encoding stats.
• GET /stats/encoding/top: Get global top encoding stats.
• GET /stats/storage/top: Get global top storage stats.

User Management

• GET /users: List all users.
• POST /users: Create a new user.
• GET /users/:id: Get a specific user.
• PUT /users/:id: Update a user.
• DELETE /users/:id: Delete a user.
• POST /users/:id/password: Reset user password.

Settings & Pages

• GET /settings: Get system settings.
• PUT /settings: Update system settings.
• GET /pages: List all web pages.
• POST /page: Create a web page.
• PUT /page: Update a web page.
• DELETE /page: Delete a web page.

Admin Encodings

• GET /admin/encodings: List all encoding jobs (admin view).

Other

• GET /move: Move items (Controller: MoveItemsController).
• GET /versioncheck: Check for updates.