youtube

# YouTube Access the YouTube Data API v3 with managed OAuth authentication. Search videos, manage playlists, access channel information, and interact with comments and subscriptions. ## Quick Start ```bash # Search for videos python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/youtube/youtube/v3/search?part=snippet&q=coding+tutorial&type=video&maxResults=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/youtube/{native-api-path} ``` Replace `{native-api-path}` with the actual YouTube Data API endpoint path. The gateway proxies requests to `www.googleapis.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Google OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=youtube&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'youtube'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "youtube", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple YouTube connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/youtube/youtube/v3/channels?part=snippet&mine=true') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Search #### Search Videos, Channels, or Playlists ```bash GET /youtube/youtube/v3/search ``` Query parameters: - `part` - Required: `snippet` - `q` - Search query - `type` - Filter by type: `video`, `channel`, `playlist` - `maxResults` - Results per page (1-50, default 5) - `order` - Sort order: `date`, `rating`, `relevance`, `title`, `viewCount` - `publishedAfter` - Filter by publish date (RFC 3339) - `publishedBefore` - Filter by publish date (RFC 3339) - `channelId` - Filter by channel - `videoDuration` - `short` (<4min), `medium` (4-20min), `long` (>20min) - `pageToken` - Pagination token **Example:** ```bash curl -s -X GET "https://gateway.maton.ai/youtube/youtube/v3/search?part=snippet&q=machine+learning&type=video&maxResults=10&order=viewCount" -H "Authorization: Bearer $MATON_API_KEY" ``` **Response:** ```json { "kind": "youtube#searchListResponse", "nextPageToken": "CAUQAA", "pageInfo": { "totalResults": 1000000, "resultsPerPage": 10 }, "items": [ { "kind": "youtube#searchResult", "id": { "kind": "youtube#video", "videoId": "abc123xyz" }, "snippet": { "publishedAt": "2024-01-15T10:00:00Z", "channelId": "UCxyz123", "title": "Machine Learning Tutorial", "description": "Learn ML basics...", "thumbnails": { "default": {"url": "https://i.ytimg.com/vi/abc123xyz/default.jpg"} }, "channelTitle": "Tech Channel" } } ] } ``` ### Videos #### Get Video Details ```bash GET /youtube/youtube/v3/videos?part=snippet,statistics,contentDetails&id={videoId} ``` Parts available: - `snippet` - Title, description, thumbnails, channel info - `statistics` - View count, likes, comments - `contentDetails` - Duration, dimension, definition - `status` - Upload status, privacy status - `player` - Embedded player HTML **Example:** ```bash curl -s -X GET "https://gateway.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ" -H "Authorization: Bearer $MATON_API_KEY" ``` #### Get My Videos (Uploaded) ```bash GET /youtube/youtube/v3/search?part=snippet&forMine=true&type=video&maxResults=25 ``` #### Rate Video (Like/Dislike) ```bash POST /youtube/youtube/v3/videos/rate?id={videoId}&rating=like ``` Rating values: `like`, `dislike`, `none` #### Get Trending Videos ```bash GET /youtube/youtube/v3/videos?part=snippet,statistics&chart=mostPopular&regionCode=US&maxResults=10 ``` #### Get Video Categories ```bash GET /youtube/youtube/v3/videoCategories?part=snippet&regionCode=US ``` ### Channels #### Get Channel Details ```bash GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&id={channelId} ``` #### Get My Channel ```bash GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true ``` **Response:** ```json { "items": [ { "id": "UCxyz123", "snippet": { "title": "My Channel", "description": "Channel description", "customUrl": "@mychannel", "publishedAt": "2020-01-01T00:00:00Z", "thumbnails": {...} }, "statistics": { "viewCount": "1000000", "subscriberCount": "50000", "videoCount": "100" }, "contentDetails": { "relatedPlaylists": { "uploads": "UUxyz123" } } } ] } ``` #### Get Channel by Username ```bash GET /youtube/youtube/v3/channels?part=snippet,statistics&forUsername={username} ``` ### Playlists #### List My Playlists ```bash GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&mine=true&maxResults=25 ``` #### Get Playlist ```bash GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&id={playlistId} ``` #### Create Playlist ```bash POST /youtube/youtube/v3/playlists?part=snippet,status Content-Type: application/json { "snippet": { "title": "My New Playlist", "description": "A collection of videos", "defaultLanguage": "en" }, "status": { "privacyStatus": "private" } } ``` Privacy values: `public`, `private`, `unlisted` #### Update Playlist ```bash PUT /youtube/youtube/v3/playlists?part=snippet,status Content-Type: application/json { "id": "PLxyz123", "snippet": { "title": "Updated Playlist Title", "description": "Updated description" }, "status": { "privacyStatus": "public" } } ``` #### Delete Playlist ```bash DELETE /youtube/youtube/v3/playlists?id={playlistId} ``` ### Playlist Items #### List Playlist Items ```bash GET /youtube/youtube/v3/playlistItems?part=snippet,contentDetails&playlistId={playlistId}&maxResults=50 ``` #### Add Video to Playlist ```bash POST /youtube/youtube/v3/playlistItems?part=snippet Content-Type: application/json { "snippet": { "playlistId": "PLxyz123", "resourceId": { "kind": "youtube#video", "videoId": "abc123xyz" }, "position": 0 } } ``` #### Remove from Playlist ```bash DELETE /youtube/youtube/v3/playlistItems?id={playlistItemId} ``` ### Subscriptions #### List My Subscriptions ```bash GET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&maxResults=50 ``` #### Check Subscription to Channel