{"skill":{"slug":"youtube-api-skill","displayName":"YouTube","summary":"YouTube Data API integration with managed OAuth. Search videos, manage playlists, access channel data, and interact with comments. Use this skill when users...","description":"---\nname: youtube\ndescription: |\n  YouTube Data API integration with managed OAuth. Search videos, manage playlists, access channel data, and interact with comments. Use this skill when users want to interact with YouTube. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).\ncompatibility: Requires network access and valid Maton API key\nmetadata:\n  author: maton\n  version: \"1.0\"\n  clawdbot:\n    emoji: 🧠\n    requires:\n      env:\n        - MATON_API_KEY\n---\n\n# YouTube\n\nAccess the YouTube Data API v3 with managed OAuth authentication. Search videos, manage playlists, access channel information, and interact with comments and subscriptions.\n\n## Quick Start\n\n**CLI:**\n\n```bash\nmaton youtube search videos 'coding tutorial' --limit 10\n```\n\n```bash\nmaton api '/youtube/youtube/v3/search?part=snippet&q=coding+tutorial&type=video&maxResults=10'\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube/youtube/v3/search?part=snippet&q=coding+tutorial&type=video&maxResults=10')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n## Base URL\n\n```\nhttps://api.maton.ai/youtube/{native-api-path}\n```\n\nMaton proxies requests to `www.googleapis.com` and automatically injects your OAuth token.\n\n## Installation\n\n**NPM:**\n```bash\nnpm install -g @maton-ai/cli\n```\n\n**Homebrew:**\n```bash\nbrew install maton-ai/cli/maton\n```\n\n## Authentication\n\n**CLI:**\n\n```bash\nmaton login                          # Opens browser for API key\nmaton login --interactive            # Skip browser, paste API key directly\nmaton whoami                         # Show current auth state\n```\n\n**Manual:**\n\n1. Sign in or create an account at [maton.ai](https://maton.ai)\n2. Go to [maton.ai/settings](https://maton.ai/settings)\n3. Copy your API key\n4. Set your API key as `MATON_API_KEY`:\n\n```bash\nexport MATON_API_KEY=\"YOUR_API_KEY\"\n```\n\n## Connection Management\n\nManage your Google OAuth connections at `https://api.maton.ai`.\n\n### List Connections\n\n**CLI:**\n\n```bash\nmaton connection list youtube --status ACTIVE\n```\n\n```bash\nmaton api -X GET /connections -f app=youtube -f status=ACTIVE\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections?app=youtube&status=ACTIVE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Create Connection\n\n**CLI:**\n\n```bash\nmaton connection create youtube\n```\n\n```bash\nmaton api /connections -f app=youtube\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'app': 'youtube'}).encode()\nreq = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Get Connection\n\n**CLI:**\n\n```bash\nmaton connection view {connection_id}\n```\n\n```bash\nmaton api /connections/{connection_id}\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"connection\": {\n    \"connection_id\": \"{connection_id}\",\n    \"status\": \"ACTIVE\",\n    \"creation_time\": \"2025-12-08T07:20:53.488460Z\",\n    \"last_updated_time\": \"2026-01-31T20:03:32.593153Z\",\n    \"url\": \"https://connect.maton.ai/?session_token=...\",\n    \"app\": \"youtube\",\n    \"metadata\": {}\n  }\n}\n```\n\nOpen the returned `url` in a browser to complete OAuth authorization.\n\n### Delete Connection\n\n**CLI:**\n\n```bash\nmaton connection delete {connection_id}\n```\n\n```bash\nmaton api -X DELETE /connections/{connection_id}\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Specifying Connection\n\nIf you have multiple YouTube connections, specify which one to use:\n\n**CLI:**\n\n```bash\nmaton youtube channel mine --connection {connection_id}\n```\n\n```bash\nmaton api '/youtube/youtube/v3/channels?part=snippet&mine=true' --connection {connection_id}\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube/youtube/v3/channels?part=snippet&mine=true')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Maton-Connection', '{connection_id}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\nIf you have multiple connections, always specify the connection to ensure requests go to the intended account.\n\n## Security & Permissions\n\n- Access is scoped to videos, channels, playlists, comments, and captions within the connected YouTube account.\n- **All write operations require explicit user approval.** Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.\n\n## API Reference\n\n### Search\n\n#### Search Videos, Channels, or Playlists\n\n```bash\nGET /youtube/youtube/v3/search\n```\n\nQuery parameters:\n- `part` - Required: `snippet`\n- `q` - Search query\n- `type` - Filter by type: `video`, `channel`, `playlist`\n- `maxResults` - Results per page (1-50, default 5)\n- `order` - Sort order: `date`, `rating`, `relevance`, `title`, `viewCount`\n- `publishedAfter` - Filter by publish date (RFC 3339)\n- `publishedBefore` - Filter by publish date (RFC 3339)\n- `channelId` - Filter by channel\n- `videoDuration` - `short` (<4min), `medium` (4-20min), `long` (>20min)\n- `pageToken` - Pagination token\n\nExample:\n\n```bash\nmaton youtube search videos 'machine learning' --limit 10 --order viewCount\n```\n\n```bash\nmaton youtube search channels 'rob pike'\n```\n\n```bash\nmaton youtube search playlists 'study music'\n```\n\n### Videos\n\n#### Get Video Details\n\n```bash\nGET /youtube/youtube/v3/videos?part=snippet,statistics,contentDetails&id=dQw4w9WgXcQ\n```\n\nParts available:\n- `snippet` - Title, description, thumbnails, channel info\n- `statistics` - View count, likes, comments\n- `contentDetails` - Duration, dimension, definition\n- `status` - Upload status, privacy status\n- `player` - Embedded player HTML\n\nExample:\n\n```bash\nmaton youtube video view dQw4w9WgXcQ\n```\n\n#### Get My Videos (Uploaded)\n\n```bash\nGET /youtube/youtube/v3/search?part=snippet&forMine=true&type=video&order=viewCount&maxResults=25\n```\n\nExample:\n\n```bash\nmaton youtube search mine --order viewCount --limit 25\n```\n\n#### Rate Video (Like/Dislike)\n\n```bash\nPOST /youtube/youtube/v3/videos/rate?id=dQw4w9WgXcQ&rating=like\n```\n\nRating values: `like`, `dislike`, `none`\n\nExample:\n\n```bash\nmaton youtube video rate dQw4w9WgXcQ --rating like\n```\n\n#### Get Trending Videos\n\n```bash\nGET /youtube/youtube/v3/videos?part=snippet,statistics&chart=mostPopular&regionCode=US&maxResults=10\n```\n\nExample:\n\n```bash\nmaton youtube video list --region US --limit 10\n```\n\n#### Get Video Categories\n\n```bash\nGET /youtube/youtube/v3/videoCategories?part=snippet&regionCode=US\n```\n\nExample:\n\n```bash\nmaton youtube video-category list --region US\n```\n\n### Channels\n\n#### Get Channel Details\n\n```bash\nGET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&id=UCBJycsmduvYEL83R_U4JriQ\n```\n\nExample:\n\n```bash\nmaton youtube channel view UCBJycsmduvYEL83R_U4JriQ\n```\n\n#### Get My Channel\n\n```bash\nGET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true\n```\n\nExample:\n\n```bash\nmaton youtube channel mine\n```\n\n**Response:**\n```json\n{\n  \"items\": [\n    {\n      \"id\": \"UCxyz123\",\n      \"snippet\": {\n        \"title\": \"My Channel\",\n        \"description\": \"Channel description\",\n        \"customUrl\": \"@mychannel\",\n        \"publishedAt\": \"2020-01-01T00:00:00Z\",\n        \"thumbnails\": {...}\n      },\n      \"statistics\": {\n        \"viewCount\": \"1000000\",\n        \"subscriberCount\": \"50000\",\n        \"videoCount\": \"100\"\n      },\n      \"contentDetails\": {\n        \"relatedPlaylists\": {\n          \"uploads\": \"UUxyz123\"\n        }\n      }\n    }\n  ]\n}\n```\n\n#### Get Channel by Username\n\n```bash\nGET /youtube/youtube/v3/channels?part=snippet,statistics&forUsername=GoogleDevelopers\n```\n\nExample:\n\n```bash\nmaton youtube channel view --username GoogleDevelopers\n```\n\nTo look up by `@handle` instead, use `maton youtube channel view --handle GoogleDevelopers`.\n\n### Playlists\n\n#### List My Playlists\n\n```bash\nGET /youtube/youtube/v3/playlists?part=snippet,contentDetails&mine=true&maxResults=25\n```\n\nExample:\n\n```bash\nmaton youtube playlist list --limit 25\n```\n\n#### Get Playlist\n\n```bash\nGET /youtube/youtube/v3/playlists?part=snippet,contentDetails&id={playlistId}\n```\n\nExample:\n\n```bash\nmaton youtube playlist view {playlistId}\n```\n\n#### Create Playlist\n\n```bash\nPOST /youtube/youtube/v3/playlists?part=snippet,status\nContent-Type: application/json\n\n{\n  \"snippet\": {\n    \"title\": \"My New Playlist\",\n    \"description\": \"A collection of videos\",\n    \"defaultLanguage\": \"en\"\n  },\n  \"status\": {\n    \"privacyStatus\": \"private\"\n  }\n}\n```\n\nPrivacy values: `public`, `private`, `unlisted`\n\nExample:\n\n```bash\nmaton youtube playlist create --title 'My New Playlist' --description 'A collection of videos' --privacy private\n```\n\n#### Update Playlist\n\n```bash\nPUT /youtube/youtube/v3/playlists?part=snippet,status\nContent-Type: application/json\n\n{\n  \"id\": \"PLxyz123\",\n  \"snippet\": {\n    \"title\": \"Updated Playlist Title\",\n    \"description\": \"Updated description\"\n  },\n  \"status\": {\n    \"privacyStatus\": \"public\"\n  }\n}\n```\n\nExample:\n\n```bash\nmaton youtube playlist update PLxyz123 --title 'Updated Playlist Title' --description 'Updated description' --privacy public\n```\n\n#### Delete Playlist\n\n```bash\nDELETE /youtube/youtube/v3/playlists?id=PLxyz123\n```\n\nExample:\n\n```bash\nmaton youtube playlist delete PLxyz123\n```\n\n### Playlist Items\n\n#### List Playlist Items\n\n```bash\nGET /youtube/youtube/v3/playlistItems?part=snippet,contentDetails&playlistId={playlistId}&maxResults=50\n```\n\nExample:\n\n```bash\nmaton youtube playlist items {playlistId} --limit 50\n```\n\n#### Add Video to Playlist\n\n```bash\nPOST /youtube/youtube/v3/playlistItems?part=snippet\nContent-Type: application/json\n\n{\n  \"snippet\": {\n    \"playlistId\": \"PLxyz123\",\n    \"resourceId\": {\n      \"kind\": \"youtube#video\",\n      \"videoId\": \"abc123xyz\"\n    },\n    \"position\": 0\n  }\n}\n```\n\nExample:\n\n```bash\nmaton youtube playlist add-video --playlist PLxyz123 --video abc123xyz --position 0\n```\n\n#### Remove from Playlist\n\n```bash\nDELETE /youtube/youtube/v3/playlistItems?id=UEx5dGVzdAAA\n```\n\nExample:\n\n```bash\nmaton youtube playlist remove-video UEx5dGVzdAAA\n```\n\nThe argument is the **playlistItem ID** (from `maton youtube playlist items {playlistId}`), not the video ID.\n\n### Subscriptions\n\n#### List My Subscriptions\n\n```bash\nGET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&maxResults=50\n```\n\nExample:\n\n```bash\nmaton youtube subscription list --limit 50\n```\n\n#### Check Subscription to Channel\n\n```bash\nGET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&forChannelId={channelId}\n```\n\nExample:\n\n```bash\nmaton youtube subscription list --for-channel {channelId}\n```\n\nThe response is empty when no subscription exists.\n\n#### Subscribe to Channel\n\n```bash\nPOST /youtube/youtube/v3/subscriptions?part=snippet\nContent-Type: application/json\n\n{\n  \"snippet\": {\n    \"resourceId\": {\n      \"kind\": \"youtube#channel\",\n      \"channelId\": \"UCxyz123\"\n    }\n  }\n}\n```\n\nExample:\n\n```bash\nmaton youtube subscription create --channel UCxyz123\n```\n\n#### Unsubscribe\n\n```bash\nDELETE /youtube/youtube/v3/subscriptions?id={subscriptionId}\n```\n\nExample:\n\n```bash\nmaton youtube subscription delete {subscriptionId}\n```\n\nThe argument is the **subscription ID** (from `maton youtube subscription list`), not the channel ID.\n\n### Comments\n\n#### List Video Comments\n\n```bash\nGET /youtube/youtube/v3/commentThreads?part=snippet,replies&videoId={videoId}&order=time&maxResults=100\n```\n\nExample:\n\n```bash\nmaton youtube comment list --video {videoId} --order time --limit 100\n```\n\n#### Add Comment to Video\n\n```bash\nPOST /youtube/youtube/v3/commentThreads?part=snippet\nContent-Type: application/json\n\n{\n  \"snippet\": {\n    \"videoId\": \"{videoId}\",\n    \"topLevelComment\": {\n      \"snippet\": {\n        \"textOriginal\": \"Great video!\"\n      }\n    }\n  }\n}\n```\n\nExample:\n\n```bash\nmaton youtube comment create --video {videoId} --text 'Great video!'\n```\n\n#### Reply to Comment\n\n```bash\nPOST /youtube/youtube/v3/comments?part=snippet\nContent-Type: application/json\n\n{\n  \"snippet\": {\n    \"parentId\": \"{commentId}\",\n    \"textOriginal\": \"Thanks for your comment!\"\n  }\n}\n```\n\nExample:\n\n```bash\nmaton youtube comment create --parent {commentId} --text 'Thanks for your comment!'\n```\n\n#### Delete Comment\n\n```bash\nDELETE /youtube/youtube/v3/comments?id={commentId}\n```\n\nExample:\n\n```bash\nmaton youtube comment delete {commentId}\n```\n\n## Pagination\n\nYouTube uses cursor-based pagination via `pageToken`. The CLI automatically paginates with `--paginate`.\n\nExample:\n\n```bash\nmaton youtube playlist items {playlistId} --paginate\n```\n\n## Code Examples\n\n### CLI\n\n```bash\n# Search videos as JSON (default format)\nmaton youtube search videos 'tutorial' --limit 10\n\n# Filter with jq — e.g., extract just video IDs and titles\n# Note: --jq requires --json\nmaton youtube search videos 'tutorial' --limit 10 \\\n  --json --jq '.items[] | {id: .id.videoId, title: .snippet.title}'\n\n# List your playlists and extract titles only\nmaton youtube playlist list --json --jq '.items[].snippet.title'\n```\n\n### JavaScript\n\n```javascript\nconst headers = {\n  'Authorization': `Bearer ${process.env.MATON_API_KEY}`\n};\n\n// Search videos\nconst results = await fetch(\n  'https://api.maton.ai/youtube/youtube/v3/search?part=snippet&q=tutorial&type=video&maxResults=10',\n  { headers }\n).then(r => r.json());\n\n// Get video details\nconst video = await fetch(\n  'https://api.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ',\n  { headers }\n).then(r => r.json());\n\n// Create playlist\nawait fetch(\n  'https://api.maton.ai/youtube/youtube/v3/playlists?part=snippet,status',\n  {\n    method: 'POST',\n    headers: { ...headers, 'Content-Type': 'application/json' },\n    body: JSON.stringify({\n      snippet: { title: 'My Playlist', description: 'Videos I like' },\n      status: { privacyStatus: 'private' }\n    })\n  }\n);\n```\n\n### Python\n\n```python\nimport os\nimport requests\n\nheaders = {'Authorization': f'Bearer {os.environ[\"MATON_API_KEY\"]}'}\n\n# Search videos\nresults = requests.get(\n    'https://api.maton.ai/youtube/youtube/v3/search',\n    headers=headers,\n    params={'part': 'snippet', 'q': 'tutorial', 'type': 'video', 'maxResults': 10}\n).json()\n\n# Get video details\nvideo = requests.get(\n    'https://api.maton.ai/youtube/youtube/v3/videos',\n    headers=headers,\n    params={'part': 'snippet,statistics', 'id': 'dQw4w9WgXcQ'}\n).json()\n\n# Create playlist\nresponse = requests.post(\n    'https://api.maton.ai/youtube/youtube/v3/playlists?part=snippet,status',\n    headers=headers,\n    json={\n        'snippet': {'title': 'My Playlist', 'description': 'Videos I like'},\n        'status': {'privacyStatus': 'private'}\n    }\n)\n```\n\n## Notes\n\n- Video IDs are 11 characters (e.g., `dQw4w9WgXcQ`)\n- Channel IDs start with `UC` (e.g., `UCxyz123`)\n- Playlist IDs start with `PL` (user) or `UU` (uploads)\n- Use `pageToken` for pagination through large result sets\n- The `part` parameter is required and determines what data is returned\n- Quota costs vary by endpoint - search is expensive (100 units), reads are cheap (1 unit)\n- Some write operations require channel verification\n- IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing\n- IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get \"Invalid API key\" errors when piping.\n\n## Error Handling\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Missing YouTube connection or invalid request |\n| 401 | Invalid or missing Maton API key |\n| 403 | Forbidden - quota exceeded or insufficient permissions |\n| 404 | Video, channel, or playlist not found |\n| 429 | Rate limited (10 req/sec per account) |\n| 4xx/5xx | Passthrough error from YouTube API |\n\n### Troubleshooting: API Key Issues\n\n**CLI:**\n\n1. Check your auth state:\n\n```bash\nmaton whoami\n```\n\n2. Verify the API key is valid by listing connections:\n\n```bash\nmaton connection list\n```\n\n**Manual:**\n\n1. Check that the `MATON_API_KEY` environment variable is set:\n\n```bash\necho $MATON_API_KEY\n```\n\n2. Verify the API key is valid by listing connections:\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Troubleshooting: Invalid App Name\n\n1. Ensure your URL path starts with `youtube`. For example:\n\n- Correct: `https://api.maton.ai/youtube/youtube/v3/search`\n- Incorrect: `https://api.maton.ai/v3/search`\n\n## Resources\n\n- [YouTube Data API Overview](https://developers.google.com/youtube/v3)\n- [Search](https://developers.google.com/youtube/v3/docs/search/list)\n- [Videos](https://developers.google.com/youtube/v3/docs/videos)\n- [Channels](https://developers.google.com/youtube/v3/docs/channels)\n- [Playlists](https://developers.google.com/youtube/v3/docs/playlists)\n- [PlaylistItems](https://developers.google.com/youtube/v3/docs/playlistItems)\n- [Subscriptions](https://developers.google.com/youtube/v3/docs/subscriptions)\n- [Comments](https://developers.google.com/youtube/v3/docs/comments)\n- [Quota Calculator](https://developers.google.com/youtube/v3/determine_quota_cost)\n- [Maton CLI Manual](https://cli.maton.ai/manual)\n- [Maton Community](https://discord.com/invite/dBfFAcefs2)\n- [Maton Support](mailto:support@maton.ai)\n","tags":{"latest":"1.0.5"},"stats":{"comments":4,"downloads":26691,"installsAllTime":112,"installsCurrent":111,"stars":140,"versions":6},"createdAt":1770193581120,"updatedAt":1781739759130},"latestVersion":{"version":"1.0.5","createdAt":1778148561936,"changelog":"- Added CLI command examples demonstrating YouTube API usage with the Maton CLI (`maton youtube ...`, `maton api ...`).\n- Added installation instructions for the Maton CLI via npm and Homebrew.\n- Updated authentication and connection management sections with CLI commands, enhancing clarity for both CLI and Python users.\n- Included command-line examples throughout the API Reference to show how to use the CLI for common tasks.\n- No functional or code changes; documentation improvements only.","license":"MIT-0"},"metadata":{"setup":[{"key":"MATON_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"byungkyu","userId":"s174c3s2kc1ehqj1ytzntezj2983e2aj","displayName":"byungkyu","image":"https://avatars.githubusercontent.com/u/16563684?v=4"},"moderation":null}