---
title: "Video hosting API: upload, embed, and webhooks with code"
description: "A video hosting API hands your product upload, transcoding, the player, and DRM through a few calls. This guide walks the real flow in code, webhooks included."
url: https://kinescope.com/blog/video-hosting-api-guide
---

[Blog](https://kinescope.com/blog)

·

[Guides](https://kinescope.com/blog)

·

Article

9

min

# Video hosting API: add video to your product without building the pipeline

A video hosting API turns adding video into a few HTTP calls: authenticate, upload, embed, handle webhooks, and decide when to buy instead of build.

 [![Lina Danilova](https://kinescope.com/blog-assets/authors/lina-d.jpeg)](https://kinescope.com/authors/lina-d)[Lina Danilova](https://kinescope.com/authors/lina-d)

Head of Content

Jun 30, 2026

![Video hosting API: player plus developer building blocks](https://kinescope.com/blog-assets/en/video-hosting-api-guide/cover.avif)

Contents

## Add video through the REST API

Upload, embed, and webhooks. Docs and SDKs live at docs.kinescope.com.

[Try free](https://app.kinescope.io/user/create?lang=en)

A video hosting API is part of every [video hosting platform](https://kinescope.com/products/video-hosting): the programmable layer over upload, [transcoding](https://kinescope.com/glossary/transcoding), delivery, the player, and [DRM](https://kinescope.com/glossary/drm). Instead of clicking through a dashboard, your product makes those same calls in code, at scale. This guide walks the practical flow: authenticate, upload a file, embed the player, and react to events with webhooks, with what each step gives you as you add video to a product.

## Key takeaways

-   A video hosting API is the programmable layer over the work of putting video online: ingest, transcoding to adaptive [HLS](https://kinescope.com/glossary/hls), storage, [CDN](https://kinescope.com/glossary/cdn) delivery, a player, DRM, and analytics.
-   The core flow is small: authenticate with a bearer token, upload a file, embed the returned video by ID, and listen for a webhook when processing finishes.
-   The player is an `<iframe></iframe>` you control from JavaScript through the IFrame Player API — useful for tracking lesson progress, gating actions, or syncing video with your own UI.
-   Building the same stack in-house means running an encoder, a multi-region CDN, a DRM license service, and a player you maintain. An API is the “buy” side of that decision.
-   Kinescope exposes all of it through one [REST API](https://kinescope.com/solutions/development-teams) and open-source SDKs, usage-based from €10 a month, so the choice is mostly about whether video is core enough to your roadmap to build yourself.

## What a video hosting API does

The API turns “put this video in our product” into a handful of requests. You send a file or a URL, the [hosting platform](https://kinescope.com/products/video-hosting) transcodes it into adaptive renditions, stores it, and serves it over a CDN. You get back an ID and an embed code, and your app never touches the heavy parts of video.

The useful way to think about a video hosting API is by what it removes from your backlog. Uploading, encoding to multiple bitrates, packaging for HLS, signing playback URLs, enforcing DRM, and collecting watch analytics are all standard problems with standard solutions. An API lets you call those solutions instead of staffing them.

![Kinescope dashboard screen where a developer creates an API access key](https://kinescope.com/blog-assets/en/video-hosting-api-guide/asset-1.avif)

Kinescope dashboard screen where a developer creates an API access key

## What you would build yourself

Building the video layer yourself means standing up a full system. To serve one uploaded file to a phone on a train and a laptop on fibre, you need:

-   **Ingest and transcoding.** Take an arbitrary MP4 or MOV and produce several resolutions, because one file can’t serve every connection. That means running and scaling an encoder.
-   **Packaging and delivery.** Segment each rendition for HLS, push it to a CDN with points of presence near your viewers, and keep [adaptive bitrate](https://kinescope.com/glossary/adaptive-bitrate) switching smooth.
-   **Protection.** Sign and expire playback URLs, restrict domains, and run a DRM license service for [Widevine and FairPlay](https://kinescope.com/blog/multi-drm-widevine-fairplay-playready) if the content is paid.
-   **A player.** Build and maintain one that handles HLS, captions, fullscreen, mobile quirks, and DRM across browsers.
-   **Analytics.** Collect view and engagement data and tie it to your own users.

Each of those is a team’s worth of ongoing work. A hosting API is the decision to rent that stack and spend your engineers on the product instead.

## Quickstart

The minimum path from nothing to a playing video is three steps: get a key, upload a file, embed the result. Here is the shape of it, using the [Kinescope video hosting API](https://kinescope.com/developers) as the example.

`# 1. Your Access Key comes from the dashboard. Treat it like any secret.   export KINESCOPE_TOKEN="your_access_key"   # 2. Confirm the key works by listing your videos.   curl -H "Authorization: Bearer $KINESCOPE_TOKEN"  \    https://api.kinescope.io/v1/videos   `

Once a video exists and its status is `done`, embedding it is one tag:

`<iframe src="https://kinescope.io/embed/VIDEO_ID"    allow="autoplay; fullscreen; picture-in-picture; encrypted-media;"    frameborder="0" allowfullscreen></iframe>   `

The rest of this guide expands each step.

## Authenticate and upload

### Authentication

Every request carries your Access Key as a bearer token. Kinescope’s API lives under `https://api.kinescope.io/v1/`, and a missing or wrong key returns `401`.

`curl -H "Authorization: Bearer $KINESCOPE_TOKEN"  \    https://api.kinescope.io/v1/videos   `

Errors come back as a JSON `error` object with a `code`, `message`, and `detail`, so you can branch on them in your client.

### Uploading a file

Kinescope accepts uploads as a resumable transfer (so a dropped connection resumes instead of restarting), and also supports importing from a URL or in bulk from CSV. The file push itself is handled by the official [SDKs](https://github.com/kinescope) and the upload flow in the [developer docs](https://docs.kinescope.com/), which give the exact uploader call for your language. Build the upload on top of those; they wrap the multipart and resumable logic for you. The four request shapes — a single call, a browser upload that never sees your token, resumable chunks and import by URL — are compared side by side in [the upload API walkthrough](https://kinescope.com/blog/video-upload-api).

### Checking when it’s ready

A freshly uploaded video becomes playable once it clears a short processing lifecycle. You can read a video’s `status` field, which is one of `pending`, `uploading`, `pre-processing`, `processing`, `done`, `aborted`, or `error`.

`curl -H "Authorization: Bearer $KINESCOPE_TOKEN"  \    https://api.kinescope.io/v1/videos/VIDEO_ID   `

Polling works, but the cleaner pattern is a webhook, covered below.

![Kinescope catalog showing a video's processing status before it becomes playable](https://kinescope.com/blog-assets/en/video-hosting-api-guide/asset-2.avif)

Kinescope catalog showing a video’s processing status before it becomes playable

## Embed and control the player

### The embed code

The player is an `<iframe></iframe>` pointed at your video ID. The `allow` attribute matters: `encrypted-media` is what lets DRM-protected video play, so keep it in even if you aren’t using DRM yet.

`<iframe src="https://kinescope.io/embed/VIDEO_ID"    allow="autoplay; fullscreen; picture-in-picture; encrypted-media;"    frameborder="0" allowfullscreen></iframe>   `

You can set playback behavior through URL parameters, for example `?autoplay=1&muted=1` or a quality cap like `?quality=720p` to save data on mobile.

![Kinescope embed dialog showing the iframe code for a video](https://kinescope.com/blog-assets/en/video-hosting-api-guide/asset-3.png)

Kinescope embed dialog showing the iframe code for a video

### Controlling it from JavaScript

For anything interactive (tracking how much of a lesson a student watched, pausing to show a quiz, advancing to the next clip), the [IFrame Player API](https://docs.kinescope.com/developer-guides/iframe-player-api/) gives you programmatic control. You load one script and declare `onKinescopeIframeAPIReady`, which runs once the API is available. If you want to see the methods fire before writing any of this, the [Kinescope video API page](https://kinescope.com/developers#player-api) runs them against a real player.

`<div id="player"></div>   <script src="https://player.kinescope.io/latest/iframe.player.js"></script>   <script>    function onKinescopeIframeAPIReady(playerFactory) {      playerFactory        .create('player', { url: 'https://kinescope.io/VIDEO_ID' })        .then(function (player) {          player.on(player.Events.Ended, function () {            // e.g. mark the lesson complete in your own backend          });        });    }   </script>   `

Methods return Promises, and you can subscribe to events like `Play`, `Pause`, and `Ended`, then tie them to state in your product.

### Controlling who can play it

Embedding a video doesn’t make it public. Access is set per video: a private link, a password, a domain allow-list, or [DRM](https://kinescope.com/solutions/video-hosting-drm) for paid content. The same controls are available through the API, so your backend can decide who receives a playable embed and on which domains it loads. For the full picture of what “secure” means in practice, see the guide to [secure video hosting](https://kinescope.com/blog/secure-video-hosting-guide).

![Kinescope privacy settings for a video showing access level and allowed domains](https://kinescope.com/blog-assets/en/video-hosting-api-guide/asset-4.avif)

Kinescope privacy settings for a video showing access level and allowed domains

## React to events with webhooks

Polling for status wastes requests. A webhook lets Kinescope call you when something changes, so your product reacts the moment a video finishes processing. You register an endpoint and the events you care about.

`curl -X POST https://api.kinescope.io/v1/webhooks  \    -H "Authorization: Bearer $KINESCOPE_TOKEN"  \    -H "Content-Type: application/json"  \    -d '{      "name": "encoding-done",      "endpoint": "https://yourapp.com/kinescope/webhook",      "events": ["media.update.status"]    }'   `

Your endpoint receives a POST when the event fires. Check that the status is `done`, then publish the video in your product.

`// Express handler   app.post('/kinescope/webhook', (req, res) => {    const { event, data } = req.body; // confirm payload fields against the docs    if (event === 'media.update.status' && data.status === 'done') {      // the video is ready — flip it live for your users    }    res.sendStatus(200);   });   `

That closes the loop: upload through the API, get notified on `done`, embed the ID.

## SDKs for your stack

You don’t have to call the REST API by hand, and the platform is [built with developers in mind](https://kinescope.com/solutions/development-teams). We publish open-source SDKs on [GitHub](https://github.com/kinescope) for JavaScript, React, Angular, iOS, Flutter, and React Native, with the player wrapped as a native component in each; Swift, Kotlin, and Vue round out the list. Each repo includes a demo you can fork.

There’s also a native Model Context Protocol (MCP) server on every plan, so an MCP-capable assistant like Claude or Cursor can search your library or trigger uploads from inside the tool you already code in. The connection snippet for each client is in the [developer hub](https://kinescope.com/developers#mcp). If you’d rather generate a client, the [OpenAPI spec](https://github.com/kinescoper/kinescope_openapi) feeds straight into code generators.

## Buy vs build: when the API pays off

Building video in-house makes sense when video *is* your product and you need control no vendor offers. For most teams, video is a feature, and the pipeline behind it is cost without differentiation.

An API moves the line from capital project to line item. With Kinescope, [delivery and the player](https://kinescope.com/products/video-player) are [usage-based from €10 a month](https://kinescope.com/pricing): you pay per gigabyte stored and delivered, with transcoding charged once at upload. There are no per-seat fees and no enterprise contract to unlock the basics, so the protections that paid content needs ([DRM](https://kinescope.com/blog/stop-video-downloading-drm), signed links, domain rules) are part of the same API rather than a separate tier.

The honest test: estimate the engineering months to build and run ingest, CDN, DRM, and a player, then compare that against a usage bill. If video isn’t where your team’s time should go, the API is the answer. Migration is usually part of that math too: most hosting platforms import an existing library for you, so moving off a self-built stack or another provider is a managed step rather than a second project.

## FAQ

It's an interface for adding video to a product programmatically: you upload a file or URL, the platform transcodes and stores it and serves it over a CDN, and you get back an ID and an embed code. Your application calls endpoints instead of running video infrastructure.

Authenticate with a bearer token, then send the file as a resumable upload (or import it from a URL). The video moves through a processing lifecycle and becomes playable when its status is done. Most platforms, Kinescope included, provide SDKs that wrap the upload so you don't build it from scratch.

Use the <iframe> embed code with your video ID, keeping the allow attribute (including encrypted-media) so DRM-protected playback works. For interactive control, load the IFrame Player API and subscribe to player events from JavaScript.

They notify your server when something changes — most often when a video finishes processing — so you can publish it the moment it's ready. You register an endpoint and the events you want, and the platform POSTs you the event.

## Read more

[![Video upload API: four ways to get a file into your library](https://kinescope.com/blog-assets/en/video-upload-api/cover.avif) ### Video upload API: four ways to get a file into your library Guides · 9 min read](https://kinescope.com/blog/video-upload-api)

[![Enterprise video streaming: when to build and when to buy](https://kinescope.com/blog-assets/en/build-vs-buy-video-streaming/cover.avif) ### Enterprise video streaming: when to build and when to buy Comparisons · 13 min read](https://kinescope.com/blog/build-vs-buy-video-streaming)

[![Cloud Video Hosting vs Self-Hosted](https://kinescope.com/blog-assets/en/cloud-video-hosting-vs-self-hosted/cover.avif) ### Cloud Video Hosting vs Self-Hosted Comparisons · 15 min read](https://kinescope.com/blog/cloud-video-hosting-vs-self-hosted)
