Pagination and limits

List endpoints return one page at a time, and every request has size and time limits. Design your integration around them from the start.

Response shapeCopy Anchor Link

A successful response wraps its payload in data. A list adds meta:

{
  "data": [
    { "id": "6f1c2b9e-4a7d-4f3e-9b8a-2d5c7e1f0a34", "title": "Lesson 26", "encoding_status": "ready" }
  ],
  "meta": { "page": 2, "per_page": 25, "total": 137 }
}

PaginationCopy Anchor Link

meta.total counts every item across all pages, so the last page is ceil(total / per_page). A page past the end returns an empty data list.

const base = 'https://api.octavideo.tech/api/v1';
const headers = { AccessKey: process.env.OCTAVIDEO_KEY };

const videos = [];
for (let page = 1; ; page++) {
  const res = await fetch(`${base}/videos?page=${page}&per_page=100`, { headers });
  if (!res.ok) throw new Error(`OctaVideo ${res.status}`);
  const { data, meta } = await res.json();
  videos.push(...data);
  if (page * meta.per_page >= meta.total) break;
}

LimitsCopy Anchor Link

Rate limitsCopy Anchor Link

When you send too many requests, the API answers 429 rate_limited with a Retry-After header in seconds. Wait that long, then retry. Playback authorization in the player is limited per library and viewer IP, which protects your videos from scripted abuse.

Strict JSONCopy Anchor Link

The API rejects JSON bodies with unknown fields, trailing data or more than one value, with 400 bad_request. Send only the documented fields, and set Content-Type: application/json.