Docs
Workspace
Folders, saved channels, and handle/URL resolvers.
Organize channels into folders, save and manage your research. 30 channels per folder hard cap on all plans.
list_folders
List the user's saved folders with channel counts. Returns folder name, ID, channel count, and creation date for each folder. No parameters required.
Show me my saved folders
create_folder
Create a new folder for organizing saved channels. Returns 409 if a folder with this name already exists. Folder limits: Starter 15, Pro 50, Ultimate unlimited.
| Parameter | Type | Default | Description |
|---|---|---|---|
| name | string | required | Folder name (1–50 chars, must be unique per user) |
Create a folder called 'Cooking Research'
rename_folder
Rename an existing folder. Pass the current folder name (or ID) and the new name. Returns 409 if the new name collides with another existing folder.
| Parameter | Type | Default | Description |
|---|---|---|---|
| folder | string | integer | required | Current folder name OR folder ID |
| new_name | string | required | New folder name (1–50 chars, must be unique) |
No example for this one.
delete_folder
Delete a folder AND unsave every channel in it. Destructive — the first call (confirm=false) returns a preview with the channel count so the user can confirm. There is no Uncategorized fallback.
| Parameter | Type | Default | Description |
|---|---|---|---|
| folder | string | integer | required | Folder name OR folder ID to delete |
| confirm | boolean | false | Set to true to confirm deletion. First call returns the channel count so you can warn the user before they confirm. |
No example for this one.
get_folder
Get all channels in a folder with live 24h growth metrics. Returns each channel's current subscriber count, view count, and the latest 24h delta (views_24h, subs_24h).
| Parameter | Type | Default | Description |
|---|---|---|---|
| folder | string | integer | required | Folder name OR folder ID |
What's new with my Cooking Research folder?
folder_outliers
Recent uploads from every channel in a folder, ranked by outlier score in one call. Each video is scored against its own channel only, at the same age, so new uploads are not penalised for being new. Every video also shows whether it is breaking out right now.
| Parameter | Type | Default | Description |
|---|---|---|---|
| folder | string | integer | required | Folder name OR folder ID |
| days | integer | 7 | Only videos uploaded in the last N days (default 7) |
| min_score | number | null | null | Only videos with adjusted_score at least this, e.g. 2 (default no floor) |
| sort | string | "outlier" | outlier (default), views or recent |
| limit | integer | 100 | Max videos, 1-500 (default 100) |
What were the outliers in my CARS folder this week?
save_channels
Save one or more channels to a folder. Channel IDs must be raw YouTube channel IDs (start with UC, 24 chars). For @handles or URLs, call resolve_handle / resolve_url first. 30 channels per folder hard cap.
| Parameter | Type | Default | Description |
|---|---|---|---|
| channel_ids | array | required | List of YouTube channel IDs (UCxxxxxxxxxxxxxxxxxxxxxx). Must be raw IDs — call resolve_handle or resolve_url first to convert @handles or URLs. |
| folder | string | integer | required | Folder name OR folder ID. There is no default folder — must be specified. |
Save the top 3 channels from my last search to 'Cooking Research'
unsave_channel
Remove a channel from the user's saved set. The channel disappears from whichever folder it was in.
| Parameter | Type | Default | Description |
|---|---|---|---|
| channel_id | string | required | YouTube channel ID (UCxxxxxxxxxxxxxxxxxxxxxx) to remove from saved channels |
No example for this one.
move_channel
Move an already-saved channel from its current folder to a different one. Returns 404 if the channel isn't currently saved. Returns 409 if the target folder is at the 30-channel cap.
| Parameter | Type | Default | Description |
|---|---|---|---|
| channel_id | string | required | YouTube channel ID (UCxxxxxxxxxxxxxxxxxxxxxx) to move |
| to_folder | string | integer | required | Destination folder name OR folder ID |
Resolvers
Convert @handles and URLs to stable channel IDs for use with workspace tools. These are narrow-use tools — search tools auto-resolve handles and URLs internally.
No example for this one.
resolve_handle
Resolve a YouTube @handle to a stable channel ID. Use only when you need a raw channel ID for save_channels. Search tools already auto-resolve handles — do NOT call this before searching.
| Parameter | Type | Default | Description |
|---|---|---|---|
| handle | string | required | A YouTube @handle (e.g. @cheftok or cheftok). The leading @ is optional. |
Save @cheftok to my Cooking Research folder
resolve_url
Resolve a YouTube channel URL or video URL to a stable channel ID. For video URLs, the owner channel is returned. Use only when you need a raw channel ID for save_channels.
| Parameter | Type | Default | Description |
|---|---|---|---|
| url | string | required | A YouTube channel URL (youtube.com/@handle, youtube.com/channel/UCxxx) or video URL (watch, shorts, youtu.be). For video URLs the owner channel is returned. |
No example for this one.