{ "openapi": "3.1.0", "info": { "title": "YTKACE Private API", "version": "1.0.0", "description": "Read-only YouTube.js18.3.0 adapter for the standalone Flutter DTO contract. Public search-based discovery; no account synchronization. Caption SSRF protection: exact-issued-track matching. Opaque media tokens only. API_KEY optional; Flutter client currently sends no Bearer token." }, "servers": [ { "url": "https://ytkace.oxygen-academy.online", "description": "Production origin: https://ytkace.oxygen-academy.online. No path prefix." } ], "paths": { "/health": { "get": { "operationId": "health", "summary": "health", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "ok" }, "service": { "type": "string" }, "version": { "type": "string" }, "upstream": { "const": "not_probed" } } } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/about": { "get": { "operationId": "about", "summary": "about", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/home": { "get": { "operationId": "home", "summary": "home", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "pageToken", "in": "query", "required": false, "description": "Opaque cursor from the previous response; process-local TTL300s.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoPage" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/search": { "get": { "operationId": "search", "summary": "search", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "pageToken", "in": "query", "required": false, "description": "Opaque cursor from the previous response; process-local TTL300s.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoPage" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resolve": { "get": { "operationId": "resolve", "summary": "resolve", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedInput" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}": { "get": { "operationId": "video", "summary": "video", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoItem" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/channels/{id}": { "get": { "operationId": "channel", "summary": "channel", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelItem" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/playlists/{id}": { "get": { "operationId": "playlist", "summary": "playlist", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistItem" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/channels/{id}/videos": { "get": { "operationId": "channelsVideos", "summary": "channelsVideos", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "pageToken", "in": "query", "required": false, "description": "Opaque cursor from the previous response; process-local TTL300s.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoPage" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/playlists/{id}/videos": { "get": { "operationId": "playlistsVideos", "summary": "playlistsVideos", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "pageToken", "in": "query", "required": false, "description": "Opaque cursor from the previous response; process-local TTL300s.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoPage" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/related": { "get": { "operationId": "related", "summary": "related", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "pageToken", "in": "query", "required": false, "description": "Opaque cursor from the previous response; process-local TTL300s.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoPage" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/streams": { "get": { "operationId": "streams", "summary": "streams", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedStreams" } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/captions": { "get": { "operationId": "captionTracks", "summary": "captionTracks", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CaptionTrack" } } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/captions": { "get": { "operationId": "captions", "summary": "captions", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "videoId", "in": "query", "required": true, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CaptionCue" } } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/skipSegments": { "get": { "operationId": "sponsorBlockCompatible", "summary": "sponsorBlockCompatible", "parameters": [ { "name": "videoID", "in": "query", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "categories", "in": "query", "required": false, "description": "JSON array of allowed SponsorBlock category names.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SponsorSegment" } } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sponsorblock/segments": { "get": { "operationId": "sponsorSegments", "summary": "sponsorSegments", "parameters": [ { "name": "videoID", "in": "query", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "categories", "in": "query", "required": false, "description": "JSON array of allowed SponsorBlock category names.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SponsorSegment" } } } } }, "default": { "description": "Structured upstream, validation, configuration, expiry or rate error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/media/{token}": { "get": { "operationId": "mediaRelay", "summary": "Stream only a previously-issued token; byte ranges and HLS URI rewriting", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full media or rewritten HLS manifest", "headers": { "Content-Range": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "string" } } } }, "206": { "description": "Partial media", "headers": { "Content-Range": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "string" } } } }, "410": { "description": "Expired or evicted token: resolve streams again", "headers": { "Content-Range": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "string" } } } }, "416": { "description": "Invalid or unsatisfiable byte range", "headers": { "Content-Range": { "schema": { "type": "string" } }, "Accept-Ranges": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "VideoItem": { "type": "object", "required": [ "id", "title", "author", "channelId", "thumbnailUrl" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "author": { "type": "string" }, "channelId": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "durationMs": { "type": [ "integer", "null" ] }, "viewCount": { "type": [ "integer", "null" ] }, "description": { "type": "string" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "isLive": { "type": "boolean" }, "directUrl": { "type": [ "string", "null" ] } } }, "ChannelItem": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "avatarUrl": { "type": "string" }, "bannerUrl": { "type": "string" }, "description": { "type": "string" }, "subscriberCount": { "type": [ "integer", "null" ] } } }, "PlaylistItem": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "author": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "videoCount": { "type": [ "integer", "null" ] }, "description": { "type": "string" } } }, "VideoPage": { "type": "object", "required": [ "items", "nextPageToken" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VideoItem" }, "maxItems": 50 }, "nextPageToken": { "type": [ "string", "null" ] } } }, "MediaStream": { "type": "object", "required": [ "id", "url", "container", "kind" ], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "Opaque server media relay URL. Resolve streams again after expiresAt or HTTP410." }, "container": { "type": "string" }, "kind": { "type": "string", "enum": [ "muxed", "video", "audio", "hls" ] }, "mimeType": { "type": "string" }, "bitrate": { "type": "integer" }, "sizeBytes": { "type": [ "integer", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "fps": { "type": [ "integer", "null" ] }, "qualityLabel": { "type": "string" }, "codec": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "audioTrackId": { "type": [ "string", "null" ] }, "isDefaultAudio": { "type": "boolean" }, "containsVideo": { "type": "boolean" }, "containsAudio": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ] } } }, "ResolvedStreams": { "type": "object", "required": [ "videoId", "streams" ], "properties": { "videoId": { "type": "string" }, "streams": { "type": "array", "items": { "$ref": "#/components/schemas/MediaStream" } }, "expiresAt": { "type": [ "string", "null" ] }, "relay": { "const": true }, "sourceClient": { "type": "string", "enum": [ "WEB", "IOS", "MWEB" ] }, "resolutionAttempts": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "CaptionTrack": { "type": "object", "required": [ "id", "videoId", "languageCode", "languageName", "url", "isAutoGenerated", "format" ], "properties": { "id": { "type": "string" }, "videoId": { "type": "string" }, "languageCode": { "type": "string" }, "languageName": { "type": "string" }, "url": { "type": "string", "description": "Exact server-issued URL for this video; arbitrary URLs are refused." }, "isAutoGenerated": { "type": "boolean" }, "format": { "const": "json3" } } }, "CaptionCue": { "type": "object", "required": [ "startMs", "endMs", "text" ], "properties": { "startMs": { "type": "integer", "minimum": 0 }, "endMs": { "type": "integer", "minimum": 0 }, "text": { "type": "string" } } }, "ResolvedInput": { "type": "object", "required": [ "kind", "id" ], "properties": { "kind": { "type": "string", "enum": [ "video", "channel", "playlist", "directMedia" ] }, "id": { "type": "string" }, "video": { "$ref": "#/components/schemas/VideoItem" }, "channel": { "$ref": "#/components/schemas/ChannelItem" }, "playlist": { "$ref": "#/components/schemas/PlaylistItem" } } }, "Error": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } } }, "requestId": { "type": "string" } } }, "SponsorSegment": { "type": "object", "properties": { "segment": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "UUID": { "type": "string" }, "category": { "type": "string" }, "actionType": { "type": "string" }, "videoDuration": { "type": "number" }, "votes": { "type": "integer" } } } }, "securitySchemes": { "OptionalBearer": { "type": "http", "scheme": "bearer", "description": "Enabled only when server API_KEY is set. Current Flutter UI has no API token field." } } } }