Docs

Workspace

Folders, saved channels, alerts, and channel resolution.

Folders, saved channels, alerts, and channel resolution — the same primitives that power the web app dashboard. Use these to programmatically organize research, monitor channels for outliers, and resolve @handle/URL inputs to channel IDs.

GET/api/folders

List the authenticated user's folders with channel counts.

Response200

{
  "success": true,
  "count": 2,
  "folders": [
    {
      "id": 12,
      "name": "Cooking Research",
      "channel_count": 7,
      "created_at": "2026-03-15T10:30:00"
    }
  ]
}

Example

curl https://api.algrow.online/api/folders \
-H "Authorization: Bearer YOUR_API_KEY"

POST/api/folders

Create a new folder. Content-Type application/json.

Body

Name	Type	Required	Description
name	string	Required	Folder name (1–50 chars, unique per user).

201 Created 400 Invalid name 403 Plan limit (Starter 15, Pro 50) 409 Name collision

Example

curl -X POST https://api.algrow.online/api/folders \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Tech Channels"}'

PATCH/api/folders/:id

Rename a folder. Body: {"name": "..."}.

200 Success 404 Folder not found 409 Name collision

Example

curl -X PATCH https://api.algrow.online/api/folders/12 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Renamed Folder"}'

DELETE/api/folders/:id

Delete a folder and unsave every channel in it. No Uncategorized fallback — the channels are removed entirely.

Response200

{ "success": true, "unsaved_channels": 5 }

Example

curl -X DELETE https://api.algrow.online/api/folders/12 \
-H "Authorization: Bearer YOUR_API_KEY"

GET/api/folders/:id/channels

List all channels in a folder with live 24h and 48h view/sub deltas. Sorted by save time descending.

200 Success 404 Folder not found

Example

curl https://api.algrow.online/api/folders/12/channels \
-H "Authorization: Bearer YOUR_API_KEY"

GET/api/folders/:id/outliers

Recent uploads from every channel in a folder, ranked by outlier score. Each video is scored against its own channel only, at the same age, so new uploads are not penalised for being new. Each video carries outlier_score, adjusted_score (steadied for very small channels; used for sorting), typical_views and breaking_out (how fast it is gaining views right now vs its own recent pace). Query params: days (default 7), min_score (adjusted, optional), sort (outlier default, views, recent), limit (default 100, max 500). Long-form only.

200 Success 404 Folder not found

Example

curl 'https://api.algrow.online/api/folders/12/outliers?days=7&min_score=2' \
-H "Authorization: Bearer YOUR_API_KEY"

POST/api/saved-channels

Save one or more channels into a folder. Hard cap of 30 channels per folder on all plans — if the request would exceed the cap, the entire save fails atomically (no partial save).

Body

Name	Type	Required	Description
channel_ids	array	Required	Array of YouTube channel IDs (`UC...`).
folder_id	integer	Required	Target folder ID.

200 Success 400 Invalid IDs / folder 403 Folder cap exceeded

Example

curl -X POST https://api.algrow.online/api/saved-channels \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"channel_ids": ["UCxxxxxx", "UCyyyyyy"], "folder_id": 12}'

DELETE/api/saved-channels/:channel_id

Remove a saved channel from all of the user's folders.

Example

curl -X DELETE https://api.algrow.online/api/saved-channels/UCxxxxxx \
-H "Authorization: Bearer YOUR_API_KEY"

POST/api/saved-channels/move

Move a saved channel from one folder to another.

Body

Name	Type	Required	Description
channel_id	string	Required	YouTube channel ID.
from_folder_id	integer	Required	Source folder ID.
to_folder_id	integer	Required	Destination folder ID.

No example for this one.

GET/api/saved-items

The videos, subjects and title formats you saved (the Saved page in the app), newest first, with counts by kind. Saved channels are listed by /api/folders/:id/channels. Each item carries the payload the Saved page draws, as it was when it was saved.

Query Parameters

Name	Type	Required	Description
kind	string	Optional	`video`, `subject` or `format`. Default all three.
folder_id	integer	Optional	Only this folder's items.

200 Success 400 Invalid kind

Example

curl "https://api.algrow.online/api/saved-items?kind=subject" \
-H "Authorization: Bearer YOUR_API_KEY"

Response200

{
  "success": true,
  "count": 1,
  "items": [
    {
      "id": 41,
      "kind": "subject",
      "key": "minecraft hardcore",
      "folder_id": 12,
      "payload": { "label": "Minecraft Hardcore", "niche": "gaming" },
      "saved_at": "2026-11-01T09:14:22+00:00"
    }
  ],
  "counts": { "video": 3, "subject": 1, "format": 0 }
}

POST/api/saved-items

Save a video, subject or title format to the Saved page. If the item is already saved, saving it again moves it to the folder you name. Without folder_id it goes to your Uncategorized folder, as it does in the app.

Body

Name	Type	Required	Description
kind	string	Required	`video`, `subject` or `format`.
video	object	Conditional	For `kind=video`. A row from `/api/viral-videos/search`. `video_id` is required; title, url, thumbnail_url, view_count, channel_id, channel_name and the rest are kept for the card.
content_type	string	Optional	For `kind=video`. `longform` (default) or `shorts`.
label	string	Conditional	For `kind=subject`. The subject's name.
template	string	Conditional	For `kind=format`. The title format, e.g. `I Tried [FOOD] For 30 Days`.
niche	string	Optional	For subjects and formats. Their niche key, when known.
folder_id	integer	Optional	Target folder. Default Uncategorized.

The response's item.key is what DELETE /api/saved-items takes. A video's key is its video_id. A subject's key is its name in lower case, and a title format's key is its template, both with spaces collapsed.

200 Saved 400 Invalid item 404 Folder not found

Example

curl -X POST https://api.algrow.online/api/saved-items \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind": "format", "template": "I Tried [FOOD] For 30 Days", "folder_id": 12}'

DELETE/api/saved-items

Remove a saved video, subject or title format. Pass kind and key (as the list returns them) in the query string or a JSON body.

200 Removed 400 Missing kind or key 404 Not saved

Example

curl -X DELETE "https://api.algrow.online/api/saved-items?kind=video&key=dQw4w9WgXcQ" \
-H "Authorization: Bearer YOUR_API_KEY"

POST/api/channels/resolve

Resolve a YouTube @handle or channel URL to a canonical channel ID. Useful when you have user input and need to call other endpoints with a stable UC... id.

Body

Name	Type	Required	Description
input	string	Required	`@handle`, `https://youtube.com/@handle`, `https://youtube.com/channel/UC...`, or a raw `UC...` id (returned unchanged).

Example

curl -X POST https://api.algrow.online/api/channels/resolve \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": "@MrBeast"}'

GET/api/alerts

List the user's saved alerts. Alerts watch for channels matching specific criteria (e.g. new outliers, high growth) and surface them in /api/alerts/triggered.

Example

curl https://api.algrow.online/api/alerts \
-H "Authorization: Bearer YOUR_API_KEY"

POST/api/alerts

Create a new alert. The filter body mirrors the search/trends params (subscribers, views, etc.) plus an alert type.

201 Created 400 Invalid filters 403 Plan alert cap reached

Example

curl -X POST https://api.algrow.online/api/alerts \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "New cooking outliers", "content_type": "longform", "filters": {"min_subs": 1000, "max_subs": 100000}}'

PATCH/api/alerts/:id

Update an alert's name, filters, or enabled state. Send any subset of fields.

Example

curl -X PATCH https://api.algrow.online/api/alerts/42 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'

DELETE/api/alerts/:id

Delete an alert. Triggered-channel history for the alert is also removed.

Example

curl -X DELETE https://api.algrow.online/api/alerts/42 \
-H "Authorization: Bearer YOUR_API_KEY"

GET/api/alerts/triggered

Channels that matched the user's saved alert filters in the last evaluation cycle (typically the last 24h). Use this as your “new matches” feed.

Query Parameters

Name	Type	Required	Default	Description
alert_id	integer	Optional	—	Restrict to one alert. Omit to merge across all alerts.
page	integer	Optional	1	Page (1–20).
per_page	integer	Optional	50	Results per page (1–50).

No example for this one.

GET/api/alerts/outlier-status

Quick poll endpoint: returns a per-alert summary of how many new channels triggered each alert. Cheap to call repeatedly — use it to drive a notification badge without paginating through /api/alerts/triggered.

Example

curl https://api.algrow.online/api/alerts/outlier-status \
-H "Authorization: Bearer YOUR_API_KEY"

PreviousYouTube Scraper NextMarket