Overview
Triggers allow you to automatically run agents when new videos are uploaded to external platforms. Currently, Mosaic supports YouTube channel monitoring, with more platforms coming soon.
When a trigger detects new content, it automatically starts an agent run with the new video, making it perfect for content creators who want to automate their video editing workflows.
Each agent supports one YouTube trigger that can monitor multiple channels.
YouTube Triggers
Monitor YouTube channels and automatically process new videos as they’re uploaded.
GET /agent/[agent_id]/triggers
Retrieve the YouTube trigger configured for an agent.
curl -X GET "https://api.mosaic.so/agent/[agent_id]/triggers" \
-H "Authorization: Bearer mk_your_api_key"
Response
{
"id": "8f7d6c5b-4a3e-2b1f-9d8c-1a2b3c4d5e6f",
"type": "youtube",
"youtube_channels": [
"https://www.youtube.com/channel/UCxxxxxx",
"https://www.youtube.com/@channelname"
],
"callback_url": "https://your-app.com/webhooks/trigger"
}
null if no trigger is configured.
Managing YouTube Channels
POST /agent/[agent_id]/triggers/add_youtube_channels
Add YouTube channels to monitor for new videos. This endpoint:
- Creates a new trigger if none exist
- Adds channels to the existing trigger if one already exists
- Supports both channel IDs and channel URLs
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"
}'
Parameters
| Field | Type | Required | Description |
|---|
| youtube_channels | string[] | ✅ | YouTube channel IDs or URLs to monitor |
| trigger_callback_url | string | null | ✅ | Webhook URL for trigger notifications (set to null to remove) |
Important:
- If a callback URL already exists, providing a new one will replace it
- Set
trigger_callback_url to null to remove the webhook URL from the trigger
POST /agent/[agent_id]/triggers/remove_youtube_channels
Stop monitoring specific YouTube channels.
curl -X POST "https://api.mosaic.so/agent/[agent_id]/triggers/remove_youtube_channels" \
-H "Authorization: Bearer mk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"youtube_channels": ["UCxxxxxxxxxxxxxx"]
}'
Trigger Webhooks
When a trigger detects new content and starts an agent run, webhooks are sent to your configured callback_url (if provided when running the agent). These webhooks follow the exact same format as manual agent runs, with the addition of a triggered_by field.
Webhook Payload
{
"flag": "RUN_STARTED",
"agent_id": "123e4567-e89b-12d3-a456-789012345678",
"run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
"status": "running",
"inputs": [
{
"video_url": "https://storage.googleapis.com/.../input.mp4",
"thumbnail_url": "https://storage.googleapis.com/.../input-thumb.jpg"
}
],
"triggered_by": {
"type": "youtube",
"channel_id": "UCxxxxxxxxxxxxxx",
"video_id": "dQw4w9WgXcQ",
"video_title": "Never Gonna Give You Up",
"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"triggered_at": "2024-01-15T10:30:00Z",
"trigger_id": "8f7d6c5b-4a3e-2b1f-9d8c-1a2b3c4d5e6f"
}
}
{
"flag": "RUN_FINISHED",
"agent_id": "123e4567-e89b-12d3-a456-789012345678",
"run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
"status": "completed",
"inputs": [
{
"video_url": "https://storage.googleapis.com/.../input.mp4",
"thumbnail_url": "https://storage.googleapis.com/.../input-thumb.jpg"
}
],
"outputs": [
{
"video_url": "https://storage.googleapis.com/.../output.mp4",
"thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg",
"completed_at": "2024-01-15T10:35:00Z"
}
],
"triggered_by": {
"type": "youtube",
"channel_id": "UCxxxxxxxxxxxxxx",
"video_id": "dQw4w9WgXcQ",
"video_title": "Never Gonna Give You Up",
"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"triggered_at": "2024-01-15T10:30:00Z",
"trigger_id": "8f7d6c5b-4a3e-2b1f-9d8c-1a2b3c4d5e6f"
}
}
The webhook payload format is identical for both manual and triggered runs. The only difference is that triggered runs include the triggered_by field, while manual API runs do not.
Complete Example
Here’s how to set up automatic video processing for a YouTube channel:
import requests
API_KEY = "mk_your_api_key"
BASE_URL = "https://api.mosaic.so"
AGENT_ID = "{agent_id}"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# Add YouTube channels to monitor
response = requests.post(
f"{BASE_URL}/agent/{AGENT_ID}/triggers/lowest_youtube_id/add_listeners",
headers=headers,
json={
"youtube_channels": [
"https://www.youtube.com/@yourchannel",
"UCxxxxxxxxxxxxxx" # Can use channel ID too
],
"trigger_callback_url": "https://your-app.com/webhooks/youtube"
}
)
# Check configured triggers
triggers_response = requests.get(
f"{BASE_URL}/agent/{AGENT_ID}/triggers",
headers=headers
)
triggers = triggers_response.json()
for trigger in triggers:
if trigger["type"] == "youtube":
print(f"Monitoring {len(trigger['youtube_channels'])} channels")
for channel in trigger["youtube_channels"]:
print(f" - {channel}")
Use Cases
- Content Repurposing: Automatically create shorts from new long-form videos
- Multi-Language Content: Generate translated versions when new videos are uploaded
- Accessibility: Add captions to all new videos automatically
- Brand Consistency: Apply your brand’s visual style to all new content
Best Practices
- Webhook Reliability: Implement proper webhook handling and error logging
- Channel Selection: Only monitor channels you have permission to process
- Error Handling: Set up alerting for failed agent runs triggered automatically
Limitations
- YouTube triggers check for new videos every 15 minutes
- Only public videos are detected
- Videos must be fully processed by YouTube before triggering
Coming Soon
- Twitter/X video monitoring
- TikTok integration
- Custom RSS feed triggers
- Dropbox/Google Drive folder monitoring
