API reference
The OctaVideo server API, endpoint by endpoint, generated from its OpenAPI spec.
The server API lets your backend upload and manage videos and issue playback OTPs. Each endpoint has its own page with parameters, request and response schemas, and code samples.
Basics
| Base URL | https://api.octavideo.tech/api/v1 |
| Authentication | The library's private key in the AccessKey header. See Authentication. |
| Format | JSON in and out, except uploads (multipart/form-data). |
| Success | The payload in data; lists add meta. See Pagination. |
| Errors | { "error": { "code", "message", "request_id" } }. See Errors. |
| Spec | OpenAPI 3.1, JSON |
Endpoints
| Method | Path | What it does |
|---|---|---|
POST | /videos/upload | Upload a video file |
POST | /videos/import | Import from Google Drive, OneDrive or a URL |
GET | /videos | List videos |
GET | /videos/{videoId} | Get a video and its processing status |
PUT | /videos/{videoId}/details | Update the title and description |
PUT | /videos/{videoId}/chapters | Replace the chapters |
POST | /videos/{videoId}/transcribe | Start a transcription |
GET | /videos/{videoId}/thumbnails | List thumbnail URLs |
POST | /collections | Create a collection |
POST | /collections/{collectionId}/videos | Add videos to a collection |
POST | /playback/otp | Issue a playback OTP and embed URL |
No in-browser playground
The server API is called from your server with your library's private key, which must never reach a browser. Try requests with cURL, or with one of the SDKs.
Use the spec in your tools
Download openapi.json to generate a typed client, import the API into Postman or Insomnia, or give an AI coding assistant the exact contract. /llms.txt lists every page of these docs as Markdown for AI agents.
Pagination and limits
How list endpoints page their results, and the size, time and rate limits of the API.
Upload a video POST
Uploads a video file as `multipart/form-data` and queues it for processing. Send the `title` part **before** the `file` part: the file is streamed straight into storage, so parts after it are ignored. If `title` is missing or blank, the file name without its extension is used. The file can be up to 10 GiB and the request may run for up to 2 hours. The new video starts in the `queued` status; poll [Get a video](#operation/getVideo) until `encoding_status` is `ready`.