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 |
No example for this one.
list_saved_items
The videos, subjects and title formats the user saved (the app's Saved page), newest first, with counts by kind. Each item carries the kind and key that unsave_item takes. Saved channels are in get_folder.
"Show the videos in my 'Ideas' folder"
| Parameter | Type | Default | Description |
|---|---|---|---|
| kind | string | null | video, subject or format. Default all three. |
| folder | string | integer | null | Folder name OR folder ID. Default every folder. |
What title formats have I saved?
save_video
Save a video to the user's Saved page, from a search_viral_videos result. If it is already saved, saving it again moves it to the folder given. Without a folder it goes to Uncategorized, as in the app.
| Parameter | Type | Default | Description |
|---|---|---|---|
| video | object | required | The video as search_viral_videos returned it. video_id is required; title, url, thumbnail and channel fields are kept for the card. |
| content_type | string | longform | longform (default) or shorts |
| folder | string | integer | null | Folder name OR folder ID. Default Uncategorized. |
Save the top two videos from that search to my 'Ideas' folder
save_subject
Save a subject (a video topic) to the user's Saved page, for example one from trending_subjects. If it is already saved, saving it again moves it to the folder given.
| Parameter | Type | Default | Description |
|---|---|---|---|
| label | string | required | The subject, as trending_subjects names it |
| niche | string | null | Its niche key, when known |
| folder | string | integer | null | Folder name OR folder ID. Default Uncategorized. |
Save that trending subject for later
save_title_format
Save a title format to the user's Saved page, for example one from trending_title_formats or get_channel_title_formats. If it is already saved, saving it again moves it to the folder given.
| Parameter | Type | Default | Description |
|---|---|---|---|
| template | string | required | The title format's template |
| niche | string | null | Its niche key, when known |
| folder | string | integer | null | Folder name OR folder ID. Default Uncategorized. |
Save the 'I Tried [FOOD] For 30 Days' format to my Ideas folder
unsave_item
Remove a saved video, subject or title format from the user's Saved page. Takes the kind and key that list_saved_items returns; a video's key is its video_id.
| Parameter | Type | Default | Description |
|---|---|---|---|
| kind | string | required | video, subject or format |
| key | string | required | The item's key from list_saved_items |
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.