---
title: "Swipefile"
description: "Save, organise, and manage your YouTube research directly from your AI assistant. The Swipefile tools let you create folders, save channels, videos, shorts, thumbnails, and video clips, and manage them — all through natural language without leaving your chat."
source: "https://dashboard.nexlev.io/docs/mcp/swipefile"
---

# Swipefile

Save, organise, and manage your YouTube research directly from your AI assistant. The Swipefile tools let you create folders, save channels, videos, shorts, thumbnails, and video clips, and manage them — all through natural language without leaving your chat.

## Prerequisites

- **Connected AI assistant** — Claude or ChatGPT with NexLev MCP connected
- **Active NexLev account** — [Connect to your AI assistant](/docs/mcp/quickstart) to get started

> **Warning**
>
> **Requires Lite, Pro, or Premium plan.** Swipefile is not available on the
> Free plan.

> **Info**
>
> **Recommended workflow:** Start by calling `list_swipefile_folders` to find an
> existing folder. If none fits, use `create_swipefile_folder`. Then use
> `save_to_swipefile`, forwarding rich fields (title, thumbnail, views, channel
> data) from other NexLev tool responses so your saved items display fully in
> the Swipefile UI.

## Tools

### List Folders

#### `list_swipefile_folders`

List all swipefile folders you own or have been shared into. Use this as the first step before saving anything — pick an existing folder rather than creating a new one each time.

**Example prompts:**

```
List my swipefile folders
```

```
Show me all my research folders
```

```
Do I have a folder for finance channel research?
```

**What it returns:**

| Field             | Description                                        |
| ----------------- | -------------------------------------------------- |
| `id`, `name`      | Folder identity                                    |
| `privacySettings` | Public / private setting                           |
| `savedItems`      | Total number of items saved in the folder          |
| `isOwner`         | Whether you are the owner or a shared collaborator |

**Parameters:** None required. Returns all accessible folders for the authenticated user.

### Create Folder

#### `create_swipefile_folder`

Create a new private swipefile folder.

**Example prompts:**

```
Create a new swipefile folder called "crime doc research"
```

```
Make a folder called "Q3 niche shortlist" in my swipefile
```

**Parameters:**

| Parameter | Required | Description                             |
| --------- | -------- | --------------------------------------- |
| `name`    | Yes      | Name for the new folder (max 100 chars) |

> **Tip**
>
> Before creating a new folder, call `list_swipefile_folders` first — you may
> already have a suitable one. Folders are permanent and accumulate over time.

### Save Item

#### `save_to_swipefile`

Save a channel, video, short, thumbnail, or video clip to a swipefile folder. The `type` field determines which fields are required.

**Example prompts:**

```
Save this channel to my "finance research" folder:
Channel ID: UC1XW0GLUlh_6NHrogyBH2uA
```

```
Find the top 5 outlier faceless channels and save them all to my "shortlist" folder
```

```
Save the top result from my channel search to "Q3 research" as type=channel
```

```
Save video xk_FU4JFnUY to my swipefile with its channel data and tag it "hook-study"
```

```
Save the 0:00–0:30 clip of video xk_FU4JFnUY to "clip bank" with description "strong pattern interrupt hook"
```

**Required fields by type:**

| `type`          | Always required                      | Also required          |
| --------------- | ------------------------------------ | ---------------------- |
| `channel`       | `folderId`, `ytChannelId`            | —                      |
| `video`         | `folderId`, `videoId`, `ytChannelId` | —                      |
| `shorts`        | `folderId`, `videoId`, `ytChannelId` | —                      |
| `thumbnail`     | `folderId`, `videoId`, `ytChannelId` | —                      |
| `part_of_video` | `folderId`, `videoId`, `ytChannelId` | `clipStart`, `clipEnd` |

**Optional enrichment fields** (forward from other NexLev tool responses for full UI display):

| Field                    | Applies to                                 | Description                                     |
| ------------------------ | ------------------------------------------ | ----------------------------------------------- |
| `channelTitle`           | all types                                  | Channel display name                            |
| `channelThumbnail`       | all types                                  | Channel avatar URL                              |
| `channelSubscriberCount` | all types                                  | Subscriber count                                |
| `channelTotalViewCount`  | all types                                  | Total channel views                             |
| `channelTotalVideoCount` | all types                                  | Total video count                               |
| `channelHasShorts`       | all types                                  | Whether channel posts Shorts                    |
| `videoTitle`             | video / shorts / thumbnail / part_of_video | Video title                                     |
| `videoThumbnail`         | video / shorts / thumbnail / part_of_video | Thumbnail URL                                   |
| `videoViews`             | video / shorts / thumbnail / part_of_video | View count                                      |
| `videoPublishDate`       | video / shorts / thumbnail / part_of_video | Publish date                                    |
| `clipStart`              | part_of_video                              | Clip start time `MM:SS`                         |
| `clipEnd`                | part_of_video                              | Clip end time `MM:SS`                           |
| `clipDescription`        | part_of_video                              | Notes about the clip (max 500 chars)            |
| `clipThumbnails[]`       | part_of_video                              | Thumbnail URLs for the clip                     |
| `tags[]`                 | all types                                  | Custom tags e.g. `["hook-study", "outlier-6x"]` |

> **Tip**
>
> **Always forward rich fields.** Tools like `find_long_form_channels`,
> `find_shorts_channels`, `youtube_channel_outliers`, and `search_videos`
> already return `channelTitle`, `channelThumbnail`, `videoTitle`,
> `videoThumbnail`, etc. Pass these directly to `save_to_swipefile` so the saved
> item displays fully in the Swipefile UI — no extra API calls needed.

> **Note**
>
> `ytChannelId` is required for every non-channel type (video, shorts,
> thumbnail, part_of_video). If you only have a video URL, call
> `youtube_video_details` or `channel_resolver` first to get the channel ID.

### List Items

#### `list_swipefile_items`

List all items saved in a folder. Supports filtering by type, tags, and free-text search, with pagination for large folders.

**Example prompts:**

```
List everything in my "crime doc research" folder
```

```
Show me all videos tagged "hook-study" in folder [folderId]
```

```
Search for "finance" in my swipefile folder
```

```
List only channels saved in my shortlist folder
```

**Parameters:**

| Parameter  | Required | Description                                                                     |
| ---------- | -------- | ------------------------------------------------------------------------------- |
| `folderId` | Yes      | ID of the folder to list (from `list_swipefile_folders`)                        |
| `search`   | No       | Free-text search across titles, channel names, and tags                         |
| `types[]`  | No       | Filter by item type: `channel`, `video`, `shorts`, `thumbnail`, `part_of_video` |
| `tags[]`   | No       | Filter to items matching all specified tags                                     |
| `page`     | No       | Page number for pagination (default: 1)                                         |
| `limit`    | No       | Items per page (default: 20, max: 100)                                          |

**What it returns** (per item):

| Field                                                            | Description                        |
| ---------------------------------------------------------------- | ---------------------------------- |
| `id`, `type`, `tags`                                             | Item identity and classification   |
| `videoId`, `ytChannelId`                                         | Source video and channel IDs       |
| `videoTitle`, `videoThumbnail`, `videoViews`, `videoPublishDate` | Video metadata                     |
| `channelTitle`, `channelThumbnail`, `channelSubscriberCount`     | Channel metadata                   |
| `clipStart`, `clipEnd`, `clipDescription`                        | Clip fields (`part_of_video` only) |
| `createdAt`                                                      | When the item was saved            |

### Update Item

#### `update_swipefile_item`

Update the tags or clip metadata on a saved item. You can only update items you saved yourself.

**Example prompts:**

```
Add tag "shortlist" to swipefile item [mediaId]
```

```
Update the clip description on item [mediaId] to "Great hook — pattern interrupt in first 3s"
```

```
Replace the tags on item [mediaId] with ["reviewed", "q3-pick"]
```

**Parameters:**

| Parameter          | Required | Description                                             |
| ------------------ | -------- | ------------------------------------------------------- |
| `mediaId`          | Yes      | ID of the item to update (from `list_swipefile_items`)  |
| `tags[]`           | No\*     | Replace the item's tag list                             |
| `clipDescription`  | No\*     | Update clip notes (max 500 chars, `part_of_video` only) |
| `clipThumbnails[]` | No\*     | Replace clip thumbnails (`part_of_video` only)          |

\*At least one updatable field is required.

> **Warning**
>
> You can only update items **you created**. Attempting to update an item
> created by another user returns an error.

### Move Item

#### `move_swipefile_item`

Move a saved item to a different folder. You can only move items you saved yourself.

**Example prompts:**

```
Move item [mediaId] to my "final shortlist" folder
```

```
Move this channel from "research" to "approved" folder
```

**Parameters:**

| Parameter     | Required | Description                                                  |
| ------------- | -------- | ------------------------------------------------------------ |
| `mediaId`     | Yes      | ID of the item to move (from `list_swipefile_items`)         |
| `newFolderId` | Yes      | ID of the destination folder (from `list_swipefile_folders`) |

> **Warning**
>
> You can only move items **you created**. Attempting to move an item created by
> another user returns an error.

### Delete Item

#### `delete_swipefile_item`

Permanently delete a saved item. This action cannot be undone. You can only delete items you saved yourself.

**Example prompts:**

```
Delete swipefile item [mediaId]
```

```
Remove the clip I saved earlier — item ID [mediaId]
```

**Parameters:**

| Parameter | Required | Description                                            |
| --------- | -------- | ------------------------------------------------------ |
| `mediaId` | Yes      | ID of the item to delete (from `list_swipefile_items`) |

> **Warning**
>
> **Permanent action.** Deleted items cannot be recovered. Confirm with the user
> before deleting, especially in shared folders.

### Folder Insights

#### `get_swipefile_folder_insights`

Get lightweight stats for a folder — useful for a quick overview before diving into items.

**Example prompts:**

```
Get insights for my "crime doc research" folder
```

```
How many collaborators does my shortlist folder have?
```

**Parameters:**

| Parameter  | Required | Description                                      |
| ---------- | -------- | ------------------------------------------------ |
| `folderId` | Yes      | ID of the folder (from `list_swipefile_folders`) |

**What it returns:**

| Field               | Description                               |
| ------------------- | ----------------------------------------- |
| `savedItems`        | Total number of items in the folder       |
| `collaboratorCount` | Number of users the folder is shared with |
| `privacySettings`   | Folder privacy setting                    |

## Troubleshooting

**`ACCESS DENIED` on every call**

- Swipefile requires LITE plan or higher. [Upgrade your plan](?required_nexlev_lite_pro_access=true) in the dashboard.
- API key callers are blocked — swipefile is OAuth-only. Make sure you're connected via OAuth (see [Quickstart](/docs/mcp/quickstart)).

**Saved item not showing in the UI**

- You likely saved a video/short/thumbnail without a `ytChannelId`. The listing aggregation joins items through their parent channel — items with no channel record are silently dropped from listings.
- Re-save with `ytChannelId` included. Call `youtube_video_details` or `channel_resolver` to get the channel ID if you don't have it.

**`You can only modify swipefile items you created yourself`**

- Update, move, and delete are restricted to the creator of each item. Ask the item's creator to make the change, or use `list_swipefile_items` to confirm ownership.

**`AUTH_REQUIRED` error**

- Your OAuth session has expired. Re-authenticate by running `/mcp` → select `nexlev` → **Authenticate** in your CLI, or reconnect via the AI assistant's connector settings.

**Quota limit reached**

- If you've hit your daily limit, [Upgrade to Pro](?required_nexlev_lite_pro_access=true) for higher limits.

## Rate Limits

> **Note**
>
> Swipefile is available on **Lite, Pro, and Premium** plans only — Free plan
> users do not have access.

| Tool | Free | Lite | Pro |
| --- | --- | --- | --- |
| List swipefile folders (`list_swipefile_folders`) | 0 | 200 | 500 |
| List swipefile items (`list_swipefile_items`) | 0 | 200 | 500 |
| Get folder insights (`get_swipefile_folder_insights`) | 0 | 100 | 300 |
| Save to swipefile (`save_to_swipefile`) | 0 | 100 | 300 |
| Update swipefile item (`update_swipefile_item`) | 0 | 50 | 200 |
| Move swipefile item (`move_swipefile_item`) | 0 | 30 | 100 |
| Delete swipefile item (`delete_swipefile_item`) | 0 | 30 | 100 |
| Create swipefile folder (`create_swipefile_folder`) | 0 | 20 | 50 |

## What's Next?

- **[Channel Search](/docs/mcp/channel-search)** — Discover channels to save to your swipefile
- **[YouTube Tools](/docs/mcp/youtube-tools)** — Get video and channel details to enrich your saved items
- **[Similar Channels](/docs/mcp/similar-channel)** — Find related channels for bulk research saves
- **[Faceless Channels](/docs/mcp/faceless-channels)** — Discover faceless outlier channels worth saving