Base URL

https://ytsubs.app

Endpoint — /subscriptions

Return a user's YouTube subscriptions (cached). This endpoint requires both api_key and google_user_id (or google_user_id_token depending on your setup)
HTTP Method GET
Path /subscriptions
Query Parameters api_key (required) — the API key assigned to the user
Authentication API key validated against an internal users table
Caching Results are cached per user and refreshed at most once every 12 hours. If cache age < 12h, cached data is returned immediately.

Example

cURL

curl https://ytsubs.app/subscriptions?api_key=YOUR_API_KEY

Response (200 OK)

{
  "lastRetrievalDate": "2025-07-03T22:12:00Z",
  "subscriptions": [
    {
      "id": "CWE0Bb1OftI...",
      "snippet": {
        "publishedAt": "2018-01-03T21:42:30.834186Z",
        "title": "Mark Rober",
        "description": "Former NASA engineer...",
        "resourceId": { "channelId": "UCY1kMZp36I..." },
        "thumbnails": { "default": { "url": "https://..." } }
      }
    },
    ...
  ]
}

Best Practices

  1. Never embed an API key in client-side code or public repos
  2. Cache responses client-side where possible to avoid repeated API calls
  3. Gracefully handle 403/401 responses — prompt the user to re-authenticate
  4. If you need a fresh result, call the endpoint — it will refresh the cached copy if 12+ hours old

Errors

All endpoints may return these errors:

  • 401 — Missing api_key or YouTube token
  • 403 — YTSubs access to YouTube has been revoked
  • 500 — Internal error (e.g., YouTube API, network problem)