# Clip command API

> KickBot API and MCP reference for the !clip command: read and change its settings, and list or delete the clips viewers made with it.

Source: https://kickbot.com/docs/api/reference/clip-command

Use these actions to set up the `!clip` chat command and manage the clips it makes.

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 `clip_command`. Use it to load only this area: `https://kickbot.com/api/v1/mcp?areas=clip_command`.

A team member needs the **Clip command** permission in Manage Team. 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: [Clip command](https://kickbot.com/docs/chat-bot/clip-command), [Clip pages](https://kickbot.com/docs/clips-vods/clip-pages).

## Actions

| Tool | REST | Access |
|---|---|---|
| [`get_clip_command_settings`](#get_clip_command_settings) | `GET /clip-command/settings` | Read |
| [`update_clip_command_settings`](#update_clip_command_settings) | `PATCH /clip-command/settings` | Write |
| [`list_command_clips`](#list_command_clips) | `GET /clip-command/clips` | Read |
| [`delete_command_clip`](#delete_command_clip) | `DELETE /clip-command/clips/{clip_id}` | Write |

## get_clip_command_settings

**Get the !clip command settings.** Read the settings of the !clip chat command: on/off, who can use it, the reply text, and the clip lengths. premium_settings_editable tells you if custom_response and the clip lengths can be changed (premium plan).

```http
GET /api/v1/clip-command/settings
```

No input fields.

## update_clip_command_settings

**Update the !clip command settings.** Change some !clip command settings. Only the fields you send change. Requires a verified account. custom_response, max_clip_length, and default_clip_length are premium settings: a free account that sends a different value gets a premium_required error and nothing is saved.

```http
PATCH /api/v1/clip-command/settings
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | boolean | No | Turn the !clip command on or off. |
| `everyone_only` | boolean | No | Everyone in chat can use it. |
| `subscriber_only` | boolean | No | Subscribers can use it (when everyone_only is false). |
| `vip_only` | boolean | No | VIPs can use it (when everyone_only is false). |
| `mod_only` | boolean | No | Moderators can use it (when everyone_only is false). |
| `custom_response` | string or string | No | Premium only. The chat reply after a clip is made, 15-300 characters. Variables: {user} (who clipped) and {clip_url}. Default "@{user} {clip_url}". Empty resets to the default. |
| `max_clip_length` | integer | No | Premium only. Longest clip in seconds a viewer can ask for (for example !clip 90), 10-240. Default 120. |
| `default_clip_length` | integer | No | Premium only. Clip length in seconds when the viewer gives no length, 10-120. Default 30. |

## list_command_clips

**List clips made with !clip.** List the finished clips viewers made with the !clip command (up to 5 minutes long). Each clip has a public page (url). total_clips counts all finished clips.

```http
GET /api/v1/clip-command/clips
```

| Field | Type | Required | Description |
|---|---|---|---|
| `sort` (query) | `"newest"` or `"oldest"` or `"most_views"` or `"least_views"` | No | Order: newest (default), oldest, most_views, or least_views. |
| `clipper_username` (query) | string | No | Only clips made by this Kick username (not case-sensitive). |
| `limit` (query) | integer | No | Max clips to return (1-100, default 50). |
| `offset` (query) | integer | No | Number of clips to skip (default 0). |

## delete_command_clip

**Delete a !clip clip.** Delete a clip made with !clip: its video files and its public page. Needs the manage_clips permission. This cannot be undone.

```http
DELETE /api/v1/clip-command/clips/{clip_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 |
|---|---|---|---|
| `clip_id` (in the path) | string | Yes | The clip id, the last part of https://kickbot.com/clip/{clip_id}. |