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

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:

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

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

Artifacts

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)