{ "openapi": "3.1.0", "info": { "title": "YouTube API — Videos and channels", "version": "1.0.0", "description": "Full details for one video or one channel." }, "servers": [ { "url": "https://api.fetchlayer.dev/youtube" } ], "security": [ { "BearerAuth": [] } ], "components": { "schemas": { "Error": { "type": "object", "description": "Every error, on every route. Branch on code and retryable rather than on the text; on a 5xx the text is generic. MCP tool errors carry the same fields in structuredContent, and as a JSON text block.", "properties": { "error": { "type": "string", "description": "What went wrong, in words. For a 400, what to change." }, "status": { "type": "integer", "description": "The HTTP status, repeated in the body." }, "code": { "type": "string", "description": "The kind of error, stable: invalid_input, unauthorized, insufficient_credits, forbidden, not_found, expired, quota_exceeded, cancelled, time_limit, temporarily_unavailable, store_unreachable, upstream_error, internal_error, tool_error. A platform may add its own; more may be added. Treat a code you do not recognise by its retryable flag." }, "retryable": { "type": "boolean", "description": "Whether asking again can succeed." }, "requestId": { "type": "string", "description": "This request’s id, also sent as the X-Request-Id header. Quote it when reporting a problem." }, "missing": { "type": "array", "items": { "type": "string" }, "description": "With invalid_input for missing required parameters: the parameters that were missing." } }, "required": [ "error", "code", "retryable", "requestId" ] } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/video": { "post": { "operationId": "video", "tags": [ "Videos and channels" ], "summary": "Get YouTube video details", "description": "Full details for one video by ID or URL: title, description, tags, channel, exact view/like/comment counts, publish date, duration, thumbnails and availability (unlisted, age-restricted, members-only, live/upcoming, countries). A private, deleted or unknown video is a 404, never an empty record.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "video": { "type": "string", "description": "A YouTube video ID (e.g. dQw4w9WgXcQ) or any video URL, including youtu.be and Shorts links." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" } }, "additionalProperties": false, "required": [ "video" ] }, "examples": { "default": { "value": { "video": "dQw4w9WgXcQ" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "description": "Always youtube-video." }, "videoId": { "type": "string", "description": "The 11-character video ID." }, "url": { "type": "string", "description": "The video’s watch URL." }, "title": { "type": "string", "description": "The video title." }, "description": { "type": "string", "description": "The full description." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The tags the uploader set; [] when none." }, "category": { "type": [ "string", "null" ], "description": "YouTube’s category for the video, e.g. Music." }, "channel": { "type": "object", "additionalProperties": true, "description": "The channel that published it: id, name, handle (or null) and url." }, "viewCount": { "type": [ "integer", "null" ], "description": "Exact view count." }, "likeCount": { "type": [ "integer", "null" ], "description": "Exact like count; null when the owner hides likes." }, "commentCount": { "type": [ "integer", "null" ], "description": "Exact comment count; null when comments are turned off or the count is not shown." }, "publishedAt": { "type": [ "string", "null" ], "description": "When the video was published (ISO 8601, with a UTC offset)." }, "uploadedAt": { "type": [ "string", "null" ], "description": "When the video was uploaded (ISO 8601, with a UTC offset)." }, "durationSeconds": { "type": [ "integer", "null" ], "description": "Length in seconds; null for a live stream in progress." }, "thumbnails": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Thumbnail images, each with url, width and height." }, "availability": { "type": "object", "additionalProperties": true, "description": "Who can watch it and how.", "properties": { "visibility": { "type": "string", "description": "public or unlisted. Private and deleted videos are a 404." }, "isAgeRestricted": { "type": "boolean", "description": "Viewers must sign in and confirm their age." }, "isMembersOnly": { "type": "boolean", "description": "Only paying channel members can watch." }, "isFamilySafe": { "type": "boolean", "description": "Marked suitable for all audiences." }, "isRegionRestricted": { "type": "boolean", "description": "Not available in every country; see availableCountries." }, "availableCountries": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 codes of the countries where it can be watched." }, "isLiveContent": { "type": "boolean", "description": "A live stream or premiere, past, current or scheduled." }, "isLiveNow": { "type": "boolean", "description": "Live right now." }, "isUpcoming": { "type": "boolean", "description": "Scheduled and not started yet." }, "commentsVisible": { "type": "boolean", "description": "The comment section is publicly visible (false when turned off or members-only)." }, "ratingsEnabled": { "type": "boolean", "description": "Likes can be given." } } }, "live": { "type": [ "object", "null" ], "additionalProperties": true, "description": "For live content: scheduledStartAt, startedAt and endedAt (ISO 8601, each null when not known); null for an ordinary video." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this result; [] when none." }, "scrapedAt": { "type": "string", "description": "When the result was produced (ISO 8601)." } }, "additionalProperties": false }, "examples": { "default": { "value": { "entityType": "youtube-video", "videoId": "dQw4w9WgXcQ", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "keywords": [ "rick astley", "Never Gonna Give You Up", "nggyu" ], "category": "Music", "channel": { "id": "UCuAXFkgsw1L7xaCfnd5JJOw", "name": "Rick Astley", "handle": "@RickAstleyYT", "url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw" }, "viewCount": 1828910987, "likeCount": 19491707, "commentCount": 2460215, "publishedAt": "2009-10-24T23:57:33-07:00", "uploadedAt": "2009-10-24T23:57:33-07:00", "durationSeconds": 213, "thumbnails": [ { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "width": 168, "height": 94 } ], "availability": { "visibility": "public", "isAgeRestricted": false, "isMembersOnly": false, "isFamilySafe": true, "isRegionRestricted": false, "availableCountries": [ "US", "GB" ], "isLiveContent": false, "isLiveNow": false, "isUpcoming": false, "commentsVisible": true, "ratingsEnabled": true }, "live": null, "notes": [] } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/channel": { "post": { "operationId": "channel", "tags": [ "Videos and channels" ], "summary": "Get YouTube channel details", "description": "A channel’s profile and about info by ID, @handle or URL: description, subscriber count (rounded by YouTube), exact total views and video count, country, join date, verification, images and links. An unknown or terminated channel is a 404, never an empty record.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "description": "A YouTube channel ID (starts with UC), @handle (e.g. @MrBeast) or channel URL." }, "format": { "type": "string", "description": "json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.", "example": "json" } }, "additionalProperties": false, "required": [ "channel" ] }, "examples": { "default": { "value": { "channel": "@MrBeast" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "description": "Always youtube-channel." }, "channelId": { "type": "string", "description": "The channel ID (starts with UC)." }, "handle": { "type": [ "string", "null" ], "description": "The @handle, or null when the channel has none." }, "url": { "type": "string", "description": "The channel URL." }, "title": { "type": "string", "description": "The channel name." }, "description": { "type": "string", "description": "The about text." }, "country": { "type": [ "string", "null" ], "description": "The country as the channel shows it; null when it sets none." }, "joinedDate": { "type": [ "string", "null" ], "description": "When the channel was created (YYYY-MM-DD)." }, "subscriberCount": { "type": [ "integer", "null" ], "description": "Approximate: YouTube rounds public subscriber counts to three significant figures. Null when the channel hides it." }, "subscriberCountText": { "type": [ "string", "null" ], "description": "The rounded count as YouTube displays it, e.g. \"4.55M subscribers\"." }, "viewCount": { "type": [ "integer", "null" ], "description": "Exact total views." }, "videoCount": { "type": [ "integer", "null" ], "description": "Exact number of videos." }, "isVerified": { "type": "boolean", "description": "Whether the channel is verified." }, "isOfficialArtist": { "type": "boolean", "description": "Whether it is an official artist channel." }, "isFamilySafe": { "type": [ "boolean", "null" ], "description": "Marked suitable for all audiences; null when not known." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "The channel’s keywords; [] when none." }, "avatar": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Avatar images, each with url, width and height." }, "banner": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Banner images, each with url, width and height." }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "External links on the channel, each with title and url." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this result; [] when none." }, "scrapedAt": { "type": "string", "description": "When the result was produced (ISO 8601)." } }, "additionalProperties": false }, "examples": { "default": { "value": { "entityType": "youtube-channel", "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "handle": "@MrBeast", "url": "https://www.youtube.com/@MrBeast", "title": "MrBeast", "country": "United States", "joinedDate": "2012-02-19", "subscriberCount": 522000000, "subscriberCountText": "522M subscribers", "viewCount": 143700252369, "videoCount": 1008, "isVerified": true, "isOfficialArtist": false, "isFamilySafe": true, "keywords": [ "mrbeast6000", "beast", "mrbeast" ], "links": [ { "title": "Follow", "url": "https://www.instagram.com/mrbeast/" } ], "notes": [] } } } } } }, "400": { "description": "invalid_input: the request needs fixing; error names the field.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized: the API key is missing or not valid.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_credits: no credits, trial or monthly allowance left.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "forbidden: this key or account is not allowed this request.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded: a request-rate limit was reached.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.", "headers": { "X-Request-Id": { "description": "The request id, equal to requestId in the body.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] } ] } } } }