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 the current link's custom poster or generated fallback thumbnail.
• GET /:UUID/:SUBUUID/subtitle/:FILE: Get subtitle file.
• GET /:UUID/:AUDIOUUID/stream/master.m3u8: Get audio stream.
• 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.

Prepared Downloads

Downloads use persistent preparation jobs so reverse proxies do not have to keep an idle request open while FFmpeg packages the selected tracks. These routes live below the configured FolderVideoQualitysPub media prefix and require the same vc_media cookie as streaming.

• POST /:UUID/download-jobs: Create or reuse a preparation job. Returns 202 while queued/preparing and 200 when an identical ready artifact is reused.
• GET /:UUID/download-jobs/:JOBUUID: Read status, progress, queue position, estimated time, manifest, and ready-file metadata.
• GET /:UUID/download-jobs/:JOBUUID/file: Transfer a ready artifact. Supports HTTP Range requests until the job expires.

Creation body:

{
  "quality": "720p",
  "container": "mkv",
  "audioUUIDs": ["audio-uuid"],
  "subtitleUUIDs": ["subtitle-uuid"]
}

Statuses are queued, preparing, ready, failed, canceled, and expired. The prior synchronous /:UUID/:QUALITY/download/:FILE attachment route has been removed; the progressive MP4 player route is unchanged.

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 published static pages.
• GET /p/page: Get sanitized rendered content for a published static page. Hidden pages return 404.

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.
• PUT /file/thumbnail: Upload a JPEG, PNG, or WebP custom poster for one link. Requires multipart form fields LinkID and thumbnail.
• DELETE /file/thumbnail: Reset one link's custom poster and fall back to the generated thumbnail. Requires LinkID.
• 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 combined delivery traffic plus PlayerTraffic and DownloadTraffic source series.
• 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 combined delivery traffic plus player/download source series.
• 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 static pages, including hidden pages.
• GET /page/:id: Get a static page for editing.
• POST /page: Create a Markdown or HTML static page.
• POST /page/preview: Render and sanitize a Markdown or HTML preview.
• PUT /page: Update content, settings, or publication state.
• DELETE /page: Delete a static page.

Admin Encodings

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

Other

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