clawbus-youtube-unified-api

Use this skill when an agent needs to call YouTube Data API v3, YouTube Analytics API v2, or YouTube Reporting API v1 through the hosted proxy at mcp.imagineapp.co. Covers videos, channels, playlists, comments, live streaming, captions, analytics reports, and reporting jobs — all via a single X-API-KEY header (no YouTube OAuth flow required).

YouTube Unified API Skill

⚠️ Authentication — Check First

Before making any API call, verify the user has provided an Mybrandmetrics API-KEY.

If no key has been provided, say:

To use the YouTube API, I need your Mybrandmetrics API-KEY. You can find this key in your Mybrandmetrics dashboard. Please share it and I'll proceed with the request.

Once you have the key, pass it as:

X-API-KEY: <the key>

Do not ask the user for a YouTube API key or OAuth token — the proxy handles authentication internally.

---

Hosted Proxy

Base URL	https://mcp.imagineapp.co
Route prefix	/youtube_api
Full example	https://mcp.imagineapp.co/youtube_api/youtube/v3/videos

---

How to Call the API (Step-by-Step)

Step 1 — Find the right endpoint

For most tasks, read references/endpoints_summary.md first. It lists all 99 endpoints grouped by domain (Videos, Channels, Analytics, etc.) with their required and optional parameters inline. This is the fastest path — you can construct a request from this file alone without touching the discovery cache.

Use references/youtube_endpoint_catalog.json when you need the full parameter schema (types, enums, defaults) for a specific method.

Only fall back to references/discovery_cache/*.json if you need the full request/response body schemas.

Step 2 — Construct the request

• GET endpoints: all parameters go in the query string
• POST / PUT endpoints: use params for query params, requestBody for the JSON body (the request_schema_ref field in the catalog tells you the body schema name)
• part parameter: only request the parts you actually need (see Part Strategy below)
• Path parameters: substitute {id}, {channelId} etc. directly into the URL

Step 3 — Send to the proxy

curl -G "https://mcp.imagineapp.co/youtube_api/youtube/v3/videos" \
  -H "X-API-KEY: USER_KEY" \
  --data-urlencode "part=snippet,statistics" \
  --data-urlencode "id=VIDEO_ID"

Step 4 — Handle pagination

If the response contains nextPageToken, pass it back as pageToken on the next call to get the next page. Use maxResults (max 50) to control page size.

---

Part Parameter Strategy

Only request the part values you actually need — each adds quota cost:

part	Contains
id	Resource ID only (cheapest)
snippet	Title, description, thumbnails, dates, tags
statistics	Views, likes, comment counts
contentDetails	Duration, definition, caption availability
status	Privacy, upload status, license
localizations	Translated titles / descriptions
player	Embedded player HTML

---

Token / LLM Efficiency Tips

• Read endpoints_summary.md once per task, not per API call — it contains everything needed to build most requests.
• Do not load openapi_proxy.json unless you need OpenAPI-formatted tool schemas — it is large (242 KB) and the summary is faster to work from.
• Do not load discovery_cache/*.json unless you need full request body schemas — these files are very large.
• Batch related reads: if you need info on two endpoints in the same domain, read the relevant section of the summary in one pass rather than two separate lookups.
• Infer part values from the user's request rather than asking a clarification question — if the user wants "video titles and view counts", that maps directly to part=snippet,statistics.

---

Quick Endpoint Index

Task	Method	Proxy path
Get video details	GET	/youtube_api/youtube/v3/videos
Search videos/channels	GET	/youtube_api/youtube/v3/search
Get channel info	GET	/youtube_api/youtube/v3/channels
List playlists	GET	/youtube_api/youtube/v3/playlists
List playlist items	GET	/youtube_api/youtube/v3/playlistItems
List comments	GET	/youtube_api/youtube/v3/commentThreads
Get subscriptions	GET	/youtube_api/youtube/v3/subscriptions
List live broadcasts	GET	/youtube_api/youtube/v3/liveBroadcasts
Upload and publish video (simple multipart)	POST	/youtube_api/upload/youtube/v3/videos
Upload video (resumable)	POST	/youtube_api/resumable/upload/youtube/v3/videos
Query analytics	GET	/youtube_api/v2/reports
List report types	GET	/youtube_api/v1/reportTypes
Create reporting job	POST	/youtube_api/v1/jobs

For the full list with parameters, see references/endpoints_summary.md.

---

Artifacts

File	Purpose	When to read
references/endpoints_summary.md	All endpoints with params, grouped by domain	Default — read this first
references/youtube_endpoint_catalog.json	Full param schemas (type, enum, required)	When you need precise param details
references/openapi_proxy.json	OpenAPI 3.1 spec for tool/function calling	Only when building tool schemas
references/discovery_cache/*.json	Raw Google discovery documents	Only for request/response body schemas

---

Regenerate Artifacts

When Google updates a discovery document, refresh all artifacts:

python scripts/sync_discovery.py

Environment overrides:

• YOUTUBE_PROXY_BASE_URL — override the hosted base URL
• YOUTUBE_PROXY_ROUTE_PREFIX — override the route prefix (default /youtube_api)