Skip to main content
POST
/
agent
/
{agent_id}
/
triggers
/
add_youtube_channels
Add YouTube Channels
curl --request POST \
  --url https://api.example.com/agent/{agent_id}/triggers/add_youtube_channels

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.

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

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

FieldTypeRequiredDescription
youtube_channelsstring[]YesList of new YouTube channel IDs or URLs to add
trigger_callback_urlstring | nullNoOptional 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_optionsobjectNoOptional trigger filters. Currently supports filter_options.duration.min_seconds and filter_options.duration.max_seconds (inclusive bounds in seconds).

​
Response

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