---
title: "Add YouTube channel listeners"
method: POST
path: "/agent/{agent_id}/triggers/add_youtube_channels"
tags: ["Triggers"]
---

# Add YouTube channel listeners

`POST /agent/{agent_id}/triggers/add_youtube_channels`

## Request

- Base URL: `https://api.mosaic.so`
- URL: `https://api.mosaic.so/agent/{agent_id}/triggers/add_youtube_channels`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Add YouTube channels to monitor for new videos. Creates a trigger if none exist, updates a trigger with matching filter options when possible, or creates a new trigger node when filter options differ. If a channel already exists on another YouTube trigger node for the same agent, it is moved to the selected trigger node. Execution is deduplicated per target Video Input so matching duplicate trigger tiles do not create duplicate runs for the same target input.

## Path parameters

- `agent_id` string, required

## Request body

- object
  - `youtube_channels` string[], required: Array of YouTube channel IDs or URLs to monitor. Channels are moved from other YouTube trigger nodes on the same agent to the selected trigger node when necessary.
  - `trigger_callback_url` string, nullable: Optional webhook URL saved on the YouTube trigger and used as `callback_url` for each triggered run. Provide `null` to clear an existing callback URL; omit the field to keep it unchanged.
  - `filter_options` YouTubeTriggerFilterOptions: Optional per-trigger filtering options for YouTube triggers. At least one of `min_seconds` or `max_seconds` must be set to activate duration filtering, and when both are provided `min_seconds` must be less than or equal to `max_seconds`.
    - `duration` object
      - `min_seconds` integer, nullable: Minimum video duration in seconds (inclusive).
      - `max_seconds` integer, nullable: Maximum video duration in seconds (inclusive).

## Response `200`

Listeners added successfully

- object
  - `message` string
  - `channel_ids` string[]: Canonical YouTube channel IDs derived from the provided inputs (e.g. URLs/handles).
  - `channels` object[]: Stable mapping of each provided input to its resolved canonical channel_id.
    - `input` string, required
    - `channel_id` string, required
  - `youtube_channel_details` YouTubeChannelDetail[]: Detailed information for each added channel including subscriber count and thumbnail.
    - `channel_id` string: YouTube channel ID
    - `channel_name` string: Display name for the YouTube channel
    - `channel_handle` string, nullable: YouTube channel handle (if available)
    - `thumbnail_url` string, nullable: URL for the channel profile picture (if available)
    - `subscriber_count` integer, nullable: Number of subscribers for the channel (if available)
  - `filter_options` YouTubeTriggerFilterOptions: Optional per-trigger filtering options for YouTube triggers. At least one of `min_seconds` or `max_seconds` must be set to activate duration filtering, and when both are provided `min_seconds` must be less than or equal to `max_seconds`.
    - `duration` object
      - `min_seconds` integer, nullable: Minimum video duration in seconds (inclusive).
      - `max_seconds` integer, nullable: Maximum video duration in seconds (inclusive).

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `404`: Resource not found

---

[API](https://skmtc.dev/mosaic/apis/mosaic-ai-api.md) - [All operations](https://skmtc.dev/mosaic/apis/mosaic-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mosaic/apis/mosaic-ai-api/revisions/c20e9fc606a4?raw)