# VODs API

> KickBot API and MCP reference for VODs: download Kick VODs, follow the download jobs, and cut clips from a VOD with the VOD editor.

Source: https://kickbot.com/docs/api/reference/vods

Use these actions to download Kick VODs and to cut clips from a VOD with the VOD editor.

Each action is a REST endpoint under `https://kickbot.com/api/v1` and an MCP tool with the same name. The MCP area name is `vods`. Use it to load only this area: `https://kickbot.com/api/v1/mcp?areas=vods`.

A team member needs one of these permissions in Manage Team: **VOD downloader** or **VOD editor**. Some actions need a specific one (the action says so). Owners and admins have every permission. Write actions also need a read and write key or connection. See [Permissions and security](https://kickbot.com/docs/api/start/permissions-and-security).

How the feature works in the dashboard: [VOD downloader](https://kickbot.com/docs/clips-vods/vod-downloader), [VOD editor](https://kickbot.com/docs/clips-vods/vod-editor).

## Actions

| Tool | REST | Access |
|---|---|---|
| [`list_vod_downloads`](#list_vod_downloads) | `GET /vods/downloads` | Read |
| [`get_kick_vod`](#get_kick_vod) | `GET /vods/kick` | Read |
| [`start_vod_download`](#start_vod_download) | `POST /vods/downloads` | Write |
| [`delete_vod_download`](#delete_vod_download) | `DELETE /vods/downloads/{id}` | Write |
| [`list_vod_editor_clips`](#list_vod_editor_clips) | `GET /vods/editor/clips` | Read |
| [`create_vod_editor_clip`](#create_vod_editor_clip) | `POST /vods/editor/clips` | Write |

## list_vod_downloads

**List VOD downloads.** List the VOD downloads of the last 14 days, newest first, with status, queue position, and download_url when complete. Files expire (expires_at): 36 hours on the free plan, 14 days on premium. Call it again to check progress.

```http
GET /api/v1/vods/downloads
```

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer | No | Max items to return (1-100, default 50). |
| `offset` (query) | integer | No | Number of items to skip (default 0). |

## get_kick_vod

**Look up a Kick VOD.** Look up a Kick VOD (past broadcast) by URL: title, channel, length, and the qualities (resolutions) you can download. Use it before start_vod_download or create_vod_editor_clip.

```http
GET /api/v1/vods/kick
```

This has an effect outside your settings (for example on your live stream).

| Field | Type | Required | Description |
|---|---|---|---|
| `video_url` (query) | string | Yes | The Kick VOD URL, for example https://kick.com/<channel>/videos/<video id>. |

## start_vod_download

**Download a Kick VOD.** Start downloading a Kick VOD as a video file. Free plans can start 2 downloads per 24 hours (failed ones do not count); premium downloads use the priority queue. A VOD that is already queued cannot be added again. Check list_vod_downloads for progress and the download_url.

```http
POST /api/v1/vods/downloads
```

Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). Rate limit: 10 per minute, 100 per day.

| Field | Type | Required | Description |
|---|---|---|---|
| `video_url` | string | Yes | The Kick VOD URL, for example https://kick.com/<channel>/videos/<video id>. |
| `resolution` | string | No | A resolution from get_kick_vod, for example 1080p60, 720p60, or audio_only. Default: the best video quality. |

## delete_vod_download

**Delete a VOD download.** Delete a finished VOD download: the file is removed and the download link stops working. This cannot be undone. Downloads that are not complete yet cannot be deleted.

```http
DELETE /api/v1/vods/downloads/{id}
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` (in the path) | integer | Yes | The download id from list_vod_downloads. |

## list_vod_editor_clips

**List VOD editor clips.** List the clips cut from Kick VODs with the VOD editor, newest first, with status and download_url when complete.

```http
GET /api/v1/vods/editor/clips
```

| Field | Type | Required | Description |
|---|---|---|---|
| `limit` (query) | integer | No | Max items to return (1-100, default 50). |
| `offset` (query) | integer | No | Number of items to skip (default 0). |

## create_vod_editor_clip

**Cut a clip from a Kick VOD.** Cut a clip from a Kick VOD in the best quality. Clips can be up to 20 minutes on the free plan and 3 hours on premium. KickBot processes it in the background; check list_vod_editor_clips for the status and download_url.

```http
POST /api/v1/vods/editor/clips
```

Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). Rate limit: 10 per minute, 100 per day.

| Field | Type | Required | Description |
|---|---|---|---|
| `video_url` | string | Yes | The Kick VOD URL, for example https://kick.com/<channel>/videos/<video id>. |
| `start_seconds` | number | Yes | Start of the clip, in seconds from the start of the VOD. Decimals are allowed. |
| `end_seconds` | number | Yes | End of the clip, in seconds from the start of the VOD. Must be after start_seconds. |
| `name` | string | Yes | Name of the clip (1-100 characters). |