> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Add YouTube Channels

> Add YouTube channels to an agent trigger.

Adds channel IDs/URLs into the selected YouTube trigger set (matched by `filter_options`). You do not need to resend previously added channels.

**Behavior:**

* Creates a new trigger if none exists
* Merges new channels into an existing trigger **with matching `filter_options`** if one exists
* Creates a new YouTube trigger node when no existing trigger has matching `filter_options`
* If a channel already exists on a different YouTube trigger node for this agent, it is moved to the selected trigger node
* Deletes emptied YouTube trigger nodes after channel moves
* Updates the webhook URL if `trigger_callback_url` is provided
* Clears the webhook URL when `trigger_callback_url` is explicitly `null`

## Request

```bash theme={null}
curl -X POST "https://api.mosaic.so/agent/[agent_id]/triggers/add_youtube_channels" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "youtube_channels": [
      "UCxxxxxxxxxxxxxx",
      "https://www.youtube.com/@mkbhd"
    ],
    "trigger_callback_url": "https://your-app.com/webhooks/youtube-trigger",
    "filter_options": {
      "duration": {
        "min_seconds": 120,
        "max_seconds": 2700
      }
    }
  }'
```

## Parameters

| Field                  | Type           | Required | Description                                                                                                                                                                                                                                     |
| ---------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `youtube_channels`     | string\[]      | Yes      | List of **new** YouTube channel IDs or URLs to add                                                                                                                                                                                              |
| `trigger_callback_url` | string \| null | No       | Optional webhook URL. If provided as a string, it **replaces** the existing webhook URL for the selected trigger node. If provided as `null`, the existing webhook URL is removed. Omit this field to keep the existing callback URL unchanged. |
| `filter_options`       | object         | No       | Optional trigger filters. Currently supports `filter_options.duration.min_seconds` and `filter_options.duration.max_seconds` (inclusive bounds in seconds).                                                                                     |

## Response

```json theme={null}
{
  "message": "YouTube channels added successfully",
  "channel_ids": [
    "UCxxxxxxxxxxxxxx",
    "UCyyyyyyyyyyyyyy"
  ],
  "channels": [
    {
      "input": "UCxxxxxxxxxxxxxx",
      "channel_id": "UCxxxxxxxxxxxxxx"
    },
    {
      "input": "https://www.youtube.com/@mkbhd",
      "channel_id": "UCyyyyyyyyyyyyyy"
    }
  ],
  "filter_options": {
    "duration": {
      "min_seconds": 120,
      "max_seconds": 2700
    }
  },
  "youtube_channel_details": [
    {
      "channel_id": "UCxxxxxxxxxxxxxx",
      "channel_name": "Channel Name",
      "channel_handle": null,
      "thumbnail_url": null,
      "subscriber_count": null
    },
    {
      "channel_id": "UCyyyyyyyyyyyyyy",
      "channel_name": "Marques Brownlee",
      "channel_handle": "@mkbhd",
      "thumbnail_url": "https://yt3.googleusercontent.com/...",
      "subscriber_count": 19200000
    }
  ]
}
```

<Note>
  **Duplicate Handling**: If you add a channel that is already monitored on the selected trigger (same filter signature), it is ignored. If that channel exists on another trigger with a different filter signature, it is removed from the other trigger and moved to the selected one.

  **Run Deduplication**: At execution time, if multiple YouTube trigger nodes still match the same new video and target the same Video Input node, Mosaic starts one run for that target (not one run per trigger tile).
</Note>