Developers

Build with KolBo

Use the KolBo API (v1) to build apps on top of videos, channels, playlists and search — and embed the KolBo player anywhere on the web.

Authentication Endpoints Embed the player Errors & limits

Overview

The API is a JSON-over-HTTPS interface. All endpoints live under https://kolbo.video/api/v1. It’s the same API our mobile apps use, so everything you can do in the app you can do with the API — within the permissions of the signed-in account.

Requests and responses use JSON with UTF-8; timestamps are ISO 8601 strings in UTC.
Successful responses are wrapped as { data, pagination, meta }.
Lists return pagination.next, an opaque cursor: pass it back as ?cursor= to get the next page; null means there’s nothing more.
IDs are opaque strings. Channel endpoints accept an ID or an @handle.

Authentication

Public data (videos, channels, search) is available without signing in. To act on behalf of a user, exchange their credentials for a session token and send it in the Authorization header. Tokens last 30 days and can be revoked by the user at any time from Where you’re signed in.

curl -X POST https://kolbo.video/api/v1/auth/signin \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"••••••••"}'

# → { "data": { "token": "…", "expiresAt": "2026-10-25T12:00:00.000Z", "user": { … } } }
# → or { "data": { "twoFactor": true, "challenge": "…" } } when 2-Step Verification is on

curl https://kolbo.video/api/v1/me -H 'authorization: Bearer <token>'

Never embed a user’s token in a public web page or share it between users. Treat it like a password.

Common endpoints

Authentication

POST	/auth/signin	Exchange email + password for a session token (or a 2-Step Verification challenge)
POST	/auth/2fa	Complete sign-in with an authenticator or recovery code
POST	/auth/signout	Revoke the current token

Account

GET	/me	The signed-in user, active channel and Premium status
PATCH	/me/settings	Update account settings
GET	/notifications	Notifications, newest first
GET · DELETE	/history	Watch history

Videos & channels

GET	/videos/:id	Video details, access decision and playback source
GET	/videos/:id/related	Related videos
GET · POST	/videos/:id/comments	List or add comments
POST	/videos/:id/reaction	Like, dislike or clear your rating
GET	/channels/:channel	Channel by id or @handle
GET	/channels/:channel/videos	A channel’s uploads (also /shorts, /playlists, /posts)
POST · PATCH · DELETE	/channels/:channel/subscription	Subscribe, change notifications or unsubscribe

Discovery

GET	/search?q=	Search videos, channels and playlists
GET	/search/suggest?q=	Autocomplete suggestions
GET	/shorts	The Clips feed
GET · POST	/playlists	Your playlists, or create one

Embed the player

Select Share → Embed below any video to copy its embed code, or build it yourself. Creators can turn off embedding for individual videos; those videos show a message with a link back to KolBo instead.

<iframe width="560" height="315"
  src="https://kolbo.video/embed/VIDEO_ID?start=30&autoplay=1&mute=1"
  title="KolBo video player" frameborder="0"
  allow="autoplay; encrypted-media; picture-in-picture; fullscreen; web-share"
  allowfullscreen></iframe>

Parameter	Values	Effect
start	seconds	Start playback at this time
autoplay	0 or 1	Start playing automatically (browsers may require mute=1)
mute	0 or 1	Start muted
loop	0 or 1	Play the video again when it ends
controls	0 or 1	Hide (0) or show (1, default) the player controls

Errors and rate limits

Errors use standard HTTP status codes and a consistent body. The message is safe to show to users.

HTTP/1.1 400 Bad Request
{ "error": { "code": "bad_request", "message": "Enter a valid email address", "fields": { "email": "Invalid email" } } }

401 unauthorized — missing or expired token.
403 forbidden — the account can’t do this (for example, a members-only video).
404 not_found, 409 conflict, 429 rate_limited — back off and retry later.

Limits are applied per user and per IP address to keep the Service fast for everyone. Automated access must follow our Terms of Service — don’t scrape, inflate metrics or download content outside the features we provide.