# 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.

**Response 200 200**

```
{
  "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). |

**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"}'
```

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

### `PATCH /api/folders/:id`

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

**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"}'
```

200 Success 404 Folder not found 409 Name collision

### `DELETE /api/folders/:id`

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

**Response 200**

```
{ "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.

**Example**

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

200 Success 404 Folder not found

### `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. |

**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}'
```

200 Success 400 Invalid IDs / folder 403 Folder cap exceeded

### `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. |

### `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, language, etc.) plus an alert type.

**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, "languages": "English"}}'
```

201 Created 400 Invalid filters 403 Plan alert cap reached

### `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). |

### `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"
```