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

# Search for videos
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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://api.maton.ai/youtube/{native-api-path}

Only the endpoints listed in the API Reference section below are supported. Maton 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:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai 2. Go to maton.ai/settings 3. Copy your API key

Connection Management

Manage your Google OAuth connections at https://api.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'youtube'}).encode()
req = urllib.request.Request('https://api.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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:

{
  "connection": {
    "connection_id": "{connection_id}",
    "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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always include this header to ensure requests go to the intended account.

Security & Permissions

API Reference

Search

#### Search Videos, Channels, or Playlists

GET /youtube/youtube/v3/search

Query parameters:

Example:

curl -s -X GET "https://api.maton.ai/youtube/youtube/v3/search?part=snippet&q=machine+learning&type=video&maxResults=10&order=viewCount" -H "Authorization: Bearer $MATON_API_KEY"

Response:

{
  "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

GET /youtube/youtube/v3/videos?part=snippet,statistics,contentDetails&id={videoId}

Parts available:

Example:

curl -s -X GET "https://api.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ" -H "Authorization: Bearer $MATON_API_KEY"

#### Get My Videos (Uploaded)

GET /youtube/youtube/v3/search?part=snippet&forMine=true&type=video&maxResults=25

#### Rate Video (Like/Dislike)

POST /youtube/youtube/v3/videos/rate?id={videoId}&rating=like

Rating values: like, dislike, none

#### Get Trending Videos

GET /youtube/youtube/v3/videos?part=snippet,statistics&chart=mostPopular®ionCode=US&maxResults=10

#### Get Video Categories

GET /youtube/youtube/v3/videoCategories?part=snippet®ionCode=US

Channels

#### Get Channel Details

GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&id={channelId}

#### Get My Channel

GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true

Response:

{
  "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

GET /youtube/youtube/v3/channels?part=snippet,statistics&forUsername={username}

Playlists

#### List My Playlists

GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&mine=true&maxResults=25

#### Get Playlist

GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&id={playlistId}

#### Create Playlist

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

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

DELETE /youtube/youtube/v3/playlists?id={playlistId}

Playlist Items

#### List Playlist Items

GET /youtube/youtube/v3/playlistItems?part=snippet,contentDetails&playlistId={playlistId}&maxResults=50

#### Add Video to Playlist

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

DELETE /youtube/youtube/v3/playlistItems?id={playlistItemId}

Subscriptions

#### List My Subscriptions

GET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&maxResults=50

#### Check Subscription to Channel

GET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&forChannelId={channelId}

#### Subscribe to Channel

POST /youtube/youtube/v3/subscriptions?part=snippet
Content-Type: application/json
{
  "snippet": {
    "resourceId": {
      "kind": "youtube#channel",
      "channelId": "UCxyz123"
    }
  }
}

#### Unsubscribe

DELETE /youtube/youtube/v3/subscriptions?id={subscriptionId}

Comments

#### List Video Comments

GET /youtube/youtube/v3/commentThreads?part=snippet,replies&videoId={videoId}&maxResults=100

#### Add Comment to Video

POST /youtube/youtube/v3/commentThreads?part=snippet
Content-Type: application/json
{
  "snippet": {
    "videoId": "abc123xyz",
    "topLevelComment": {
      "snippet": {
        "textOriginal": "Great video!"
      }
    }
  }
}

#### Reply to Comment

POST /youtube/youtube/v3/comments?part=snippet
Content-Type: application/json
{
  "snippet": {
    "parentId": "comment123",
    "textOriginal": "Thanks for your comment!"
  }
}

#### Delete Comment

DELETE /youtube/youtube/v3/comments?id={commentId}

Code Examples

JavaScript

const headers = {
  'Authorization': Bearer ${process.env.MATON_API_KEY}
};
// Search videos
const results = await fetch(
  'https://api.maton.ai/youtube/youtube/v3/search?part=snippet&q=tutorial&type=video&maxResults=10',
  { headers }
).then(r => r.json());
// Get video details
const video = await fetch(
  'https://api.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ',
  { headers }
).then(r => r.json());
// Create playlist
await fetch(
  'https://api.maton.ai/youtube/youtube/v3/playlists?part=snippet,status',
  {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      snippet: { title: 'My Playlist', description: 'Videos I like' },
      status: { privacyStatus: 'private' }
    })
  }
);

Python

import os
import requests
headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
Search videos
results = requests.get(
    'https://api.maton.ai/youtube/youtube/v3/search',
    headers=headers,
    params={'part': 'snippet', 'q': 'tutorial', 'type': 'video', 'maxResults': 10}
).json()
Get video details
video = requests.get(
    'https://api.maton.ai/youtube/youtube/v3/videos',
    headers=headers,
    params={'part': 'snippet,statistics', 'id': 'dQw4w9WgXcQ'}
).json()
Create playlist
response = requests.post(
    'https://api.maton.ai/youtube/youtube/v3/playlists?part=snippet,status',
    headers=headers,
    json={
        'snippet': {'title': 'My Playlist', 'description': 'Videos I like'},
        'status': {'privacyStatus': 'private'}
    }
)

Notes

Error Handling

| Status | Meaning | |--------|---------| | 400 | Missing YouTube connection or invalid request | | 401 | Invalid or missing Maton API key | | 403 | Forbidden - quota exceeded or insufficient permissions | | 404 | Video, channel, or playlist not found | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from YouTube API |

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with youtube. For example:

Resources

# Search for videos
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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