{ "openapi": "3.2.0", "info": { "title": "transcript.im Public API", "version": "1.0.0", "description": "Extract transcripts, run batches, inspect usage, and discover YouTube content through the versioned public API." }, "servers": [ { "url": "https://api.transcript.im", "description": "Production" } ], "components": { "schemas": { "Transcript": { "type": "object", "required": [ "id", "platform", "externalId", "lang", "source", "status", "segments", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "linkedin", "twitter" ], "description": "Public /v1 platform. Local file uploads use the first-party /api/upload + async flow." }, "externalId": { "type": "string", "description": "Platform-native content id. For YouTube this is the 11-char video id." }, "sourceUrl": { "type": "string", "format": "uri", "nullable": true }, "lang": { "type": "string" }, "title": { "type": "string", "nullable": true }, "channel": { "type": "string", "nullable": true }, "creatorName": { "type": "string", "nullable": true }, "creatorHandle": { "type": "string", "nullable": true }, "creatorUrl": { "type": "string", "nullable": true }, "thumbnailUrl": { "type": "string", "nullable": true }, "durationSec": { "type": "integer", "nullable": true }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "source": { "type": "string", "enum": [ "youtube_transcript_api", "yt_dlp", "asr", "linkedin_captions", "manual" ] }, "status": { "type": "string", "enum": [ "pending", "ready", "error" ] }, "segments": { "type": "array", "items": { "type": "object", "required": [ "text", "start", "duration" ], "properties": { "text": { "type": "string" }, "start": { "type": "number" }, "duration": { "type": "number" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BatchJob": { "type": "object", "required": [ "id", "mode", "lang", "total", "done", "failed", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "batch", "playlist", "channel" ] }, "lang": { "type": "string" }, "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" }, "counts": { "type": "object", "required": [ "total", "pending", "success", "failed" ], "properties": { "total": { "type": "integer" }, "pending": { "type": "integer" }, "success": { "type": "integer" }, "failed": { "type": "integer" } } }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] }, "exportRef": { "type": "string", "nullable": true }, "exportMime": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BatchItem": { "type": "object", "required": [ "id", "platform", "externalId", "lang", "status", "attempts" ], "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "linkedin", "twitter" ] }, "externalId": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri", "nullable": true }, "lang": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "success", "failed", "skipped" ] }, "transcriptRef": { "type": "string", "format": "uuid", "nullable": true }, "error": { "type": "string", "nullable": true }, "attempts": { "type": "integer" } } }, "LibraryItem": { "type": "object", "required": [ "id", "platform", "externalId", "lang", "words", "durationSec", "starred", "createdAt" ], "properties": { "kind": { "type": "string", "enum": [ "transcript", "batch", "failed", "pending" ] }, "id": { "type": "string", "format": "uuid" }, "batchId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid" }, "jobStatus": { "type": "string", "enum": [ "pending", "processing", "failed" ] }, "platform": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "linkedin", "twitter", "upload" ] }, "externalId": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri", "nullable": true }, "lang": { "type": "string" }, "title": { "type": "string", "nullable": true }, "channel": { "type": "string", "nullable": true }, "thumbnailUrl": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "itemCount": { "type": "integer" }, "batchStatus": { "type": "string" }, "failedCount": { "type": "integer", "minimum": 0 }, "errorCode": { "type": "string", "nullable": true, "description": "Terminal failure reason for kind=failed; null for content rows." }, "words": { "type": "integer" }, "durationSec": { "type": "number", "nullable": true }, "starred": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Developer API key with the appropriate scope." }, "bearer": { "type": "http", "scheme": "bearer", "description": "Session token (cookie-based auth in browser) or developer API key (`tr_` prefix). API keys require the `transcripts` scope for /v1/transcript and the `batches` scope for /v1/batch." } } }, "security": [ { "bearer": [] } ], "paths": { "/v1/transcript": { "post": { "summary": "Extract transcript", "operationId": "extractTranscript", "tags": [ "transcripts" ], "description": "Extract a transcript for one video from YouTube, TikTok, Instagram, LinkedIn, or Twitter/X. Pass `url` (full URL, short link, or bare platform id) and the platform is auto-detected, or pass `platform` + `externalId`. The response is served from cache (Redis → Postgres) when available.\n\n`language` is a priority list (`de,en,asr`); `asr` / `asr-` request asynchronous audio transcription. When the video has no caption track (or an `asr` entry is reached) the call returns **202** with a `jobId` — poll `GET /v1/transcript/job/{id}`. Caption tracks that exist only in other languages also continue to ASR rather than failing; only a genuinely missing asset returns **404**.\n\n`waitMs` (default 2000, max 10000) is how long the caller waits before a durable **202** is returned; `0` returns a job immediately on a cache miss.\n\nA `multipart/form-data` body with a `file` field uploads local media (account-only) instead of a remote link.\n\n**Billing**: transcript extraction and cache lookup are free (0 credits).", "security": [ { "bearer": [] }, { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "platform": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "linkedin", "twitter" ] }, "externalId": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "default": "en", "type": "string", "minLength": 1, "maxLength": 200 }, "format": { "default": "json", "type": "string", "enum": [ "json", "text" ] }, "includeTimestamp": { "default": true, "type": "boolean" }, "sendMetadata": { "default": false, "type": "boolean" }, "waitMs": { "default": 2000, "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "language", "format", "includeTimestamp", "sendMetadata", "waitMs" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "language": { "type": "string", "description": "Comma-separated priority list of BCP-47 tags and/or `asr` codes." }, "format": { "type": "string", "enum": [ "json", "text" ] }, "includeTimestamp": { "type": "boolean" }, "sendMetadata": { "type": "boolean" }, "waitMs": { "type": "integer", "minimum": 0, "maximum": 10000 } } } } } }, "responses": { "200": { "description": "Transcript returned (cache hit or freshly extracted).", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "format", "cached", "language", "metadataStatus" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "format": { "type": "string", "enum": [ "json", "text" ] }, "transcript": { "oneOf": [ { "$ref": "#/components/schemas/Transcript" }, { "type": "string", "description": "Present when `format=text`; the plain-text transcript." } ] }, "text": { "type": "string", "description": "Present when `format=text`." }, "cached": { "type": "boolean" }, "language": { "type": "string" }, "metadataStatus": { "type": "string", "enum": [ "complete", "partial", "pending", "unavailable" ] }, "lengthSeconds": { "type": "integer", "nullable": true }, "lengthText": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true } } } } } }, "202": { "description": "No caption track — queued for async audio transcription. Poll GET /v1/transcript/job/{id}.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "jobId", "stage" ], "properties": { "status": { "type": "string", "enum": [ "pending", "processing" ] }, "jobId": { "type": "string", "format": "uuid" }, "stage": { "type": "string", "enum": [ "queued", "caption_fetch", "duration_check", "asr_queued", "asr_running", "publishing", "done" ] }, "metadataStatus": { "type": "string", "enum": [ "complete", "partial", "pending", "unavailable" ] } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "402": { "description": "Insufficient credits — upgrade required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "UPGRADE_REQUIRED", "TRANSCRIPT_QUOTA_EXCEEDED", "INSUFFICIENT_CREDITS", "VIDEO_TOO_LONG" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "Forbidden — API key lacks `transcripts` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "No transcript (with `availableLanguages` when known).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "422": { "description": "Validation error (invalid externalId, unsupported lang, etc.).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } } } } } }, "/v1/transcript/info": { "get": { "summary": "Get metadata", "operationId": "getTranscriptInfo", "tags": [ "transcripts" ], "description": "Resolve a video and return its metadata plus the caption languages we can serve (including `asr` availability). Free; no credits are consumed.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "url", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Full URL, short link, or bare id. Alternatively pass `platform` + `externalId`." }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "linkedin", "twitter" ] } }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Metadata and available languages.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform", "externalId", "availableLanguages" ], "properties": { "platform": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "linkedin", "twitter" ] }, "externalId": { "type": "string" }, "sourceUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "channel": { "type": "string", "nullable": true }, "creator": { "type": "string", "nullable": true }, "thumbnailUrl": { "type": "string", "nullable": true }, "lengthSeconds": { "type": "number", "nullable": true }, "lengthText": { "type": "string", "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "availableLanguages": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Could not resolve the input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Video not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "422": { "description": "The platform refused the lookup (for example, login required).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "429": { "description": "Upstream rate limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "502": { "description": "Upstream metadata fetch failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "503": { "description": "Metadata service unavailable or timed out.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/transcript/job/{id}": { "get": { "summary": "Get job status", "operationId": "getTranscriptJob", "tags": [ "transcripts" ], "description": "Poll the `jobId` returned by POST /v1/transcript's 202 response (a caption-less video queued for ASR). Owner-scoped.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status — pending/processing, or terminal with transcript/error.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "status", "jobId", "stage" ], "properties": { "status": { "type": "string", "enum": [ "pending", "processing" ] }, "jobId": { "type": "string" }, "stage": { "type": "string", "enum": [ "queued", "caption_fetch", "duration_check", "asr_queued", "asr_running", "publishing", "done" ] }, "metadataStatus": { "type": "string", "enum": [ "complete", "partial", "pending", "unavailable" ] } } }, { "type": "object", "required": [ "status", "jobId", "stage", "format", "transcript" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "jobId": { "type": "string" }, "stage": { "type": "string", "enum": [ "done" ] }, "format": { "type": "string", "enum": [ "json", "text" ] }, "cached": { "type": "boolean" }, "language": { "type": "string" }, "metadataStatus": { "type": "string", "enum": [ "complete", "partial", "pending", "unavailable" ] }, "lengthSeconds": { "type": "integer", "nullable": true }, "lengthText": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true }, "transcript": { "$ref": "#/components/schemas/Transcript" }, "text": { "type": "string", "description": "Present when `format=text`." } } }, { "type": "object", "required": [ "status", "error" ], "properties": { "status": { "type": "string", "enum": [ "failed" ] }, "jobId": { "type": "string" }, "stage": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" } } } } } ] } } } }, "400": { "description": "Invalid job id.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "403": { "description": "Forbidden — API key lacks `transcripts` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Job not found, or not owned by this credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/transcript/job/{id}/events": { "get": { "summary": "Stream job events", "operationId": "streamTranscriptJobEvents", "tags": [ "transcripts" ], "description": "Server-Sent Events for one async transcript job. A `snapshot` event is always emitted first (so a completion that happened before subscribing is not lost), followed by `stage` events and a terminal `completed` or `failed`. Owner-scoped; reconnect on a dropped stream. `EventSource` cannot set headers, so authenticated clients use fetch/streaming.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event stream (`text/event-stream`).", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE frames: `event: snapshot|stage|completed|failed` with a JSON `data:` payload." } } } }, "400": { "description": "Invalid job id.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "403": { "description": "Forbidden — API key lacks `transcripts` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Job not found, or not owned by this credential.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/batch": { "post": { "summary": "Create batch", "operationId": "createBatch", "tags": [ "batches" ], "description": "Create a batch job. The body's shape selects the mode — no `mode` field:\n- `{ urls: [...] }` — mixed-platform URLs (max 500 resolved items).\n- `{ playlistId | playlist }` — a YouTube playlist id or URL.\n- `{ channelId | channel }` — a YouTube channel id, @handle, or URL.\n\n**Billing**: batch extraction is free (0 credits); exports are Pro-gated.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "urls": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "language": { "default": "en", "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "required": [ "urls", "language" ], "additionalProperties": false }, { "type": "object", "properties": { "playlistId": { "type": "string", "minLength": 1, "maxLength": 2048 }, "language": { "default": "en", "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "required": [ "playlistId", "language" ], "additionalProperties": false }, { "type": "object", "properties": { "playlist": { "type": "string", "minLength": 1, "maxLength": 2048 }, "language": { "default": "en", "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "required": [ "playlist", "language" ], "additionalProperties": false }, { "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1, "maxLength": 2048 }, "language": { "default": "en", "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "required": [ "channelId", "language" ], "additionalProperties": false }, { "type": "object", "properties": { "channel": { "type": "string", "minLength": 1, "maxLength": 2048 }, "language": { "default": "en", "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "required": [ "channel", "language" ], "additionalProperties": false } ] } } } }, "responses": { "202": { "description": "Batch job created and queued.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "batch" ], "properties": { "batch": { "type": "object", "required": [ "id", "status", "counts" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "counts": { "type": "object", "required": [ "total", "pending", "success", "failed" ], "properties": { "total": { "type": "integer" }, "pending": { "type": "integer" }, "success": { "type": "integer" }, "failed": { "type": "integer" } } } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "402": { "description": "Batch limit exceeded for the current plan.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "Forbidden — API key lacks `batches` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } } } } } }, "/v1/batch/{batchId}": { "get": { "summary": "Get batch status", "operationId": "getBatch", "tags": [ "batches" ], "description": "Status + counts + the first page of items (cursor-paginated with `pageToken` / `maxResults`). Returns `nextPageToken` when more items remain.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from a previous `nextPageToken`." }, { "name": "maxResults", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "Batch job status with counts and an items page.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "batch", "items" ], "properties": { "batch": { "$ref": "#/components/schemas/BatchJob" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItem" } }, "nextPageToken": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "403": { "description": "Forbidden — not your batch or insufficient scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Batch not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/batch/{batchId}/export": { "get": { "summary": "Export batch", "operationId": "exportBatch", "tags": [ "batches" ], "description": "Download the results of a completed batch. Formats: `txt`, `csv`, `json`, `srt`, `vtt`, `zip` (default). Pro-gated.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "txt", "csv", "json", "srt", "vtt", "zip" ], "default": "zip" } } ], "responses": { "200": { "description": "Export file streamed directly.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } }, "application/x-subrip": { "schema": { "type": "string" } }, "text/vtt": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "402": { "description": "Upgrade required to download batch exports.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "403": { "description": "Forbidden — not your batch or insufficient scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Batch not found or export not ready yet.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "409": { "description": "Batch is not yet completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/batch/{batchId}/retry": { "post": { "summary": "Retry failed items", "operationId": "retryBatch", "tags": [ "batches" ], "description": "Re-enqueue the failed items of a settled batch. Returns 409 while the batch is still in progress or when there is nothing to retry.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch with retried items re-enqueued.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "batch", "retried" ], "properties": { "batch": { "type": "object", "additionalProperties": true }, "retried": { "type": "integer" } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "403": { "description": "Forbidden — not your batch or insufficient scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Batch not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "409": { "description": "Batch still in progress, or no failed items.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/library/transcripts": { "get": { "summary": "List library transcripts", "operationId": "listLibraryTranscripts", "tags": [ "library" ], "description": "List the saved content owned by the authenticated account: single transcripts and batch records, with server-side search, platform/language filters, sort and pagination. Never returns another owner's rows or reads the shared cache.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "starred", "history" ], "default": "all" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Case-insensitive search over saved titles/channels." }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "upload", "linkedin", "twitter", "batch" ] } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 20 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent", "oldest", "title" ], "default": "recent" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } } ], "responses": { "200": { "description": "A page of saved content.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "transcripts", "total", "page", "pageSize" ], "properties": { "transcripts": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryItem" } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1 }, "langs": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Query validation failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "403": { "description": "Forbidden — API key lacks `transcripts` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } } } } } }, "/v1/library/transcripts/{platform}/{externalId}/download": { "get": { "summary": "Download transcript", "operationId": "downloadTranscript", "tags": [ "library" ], "description": "Export a transcript saved in the owner's library as `txt`, `srt`, `vtt`, `json`, or `md`. Requires a paid plan (same gate as batch export). Omit `language` for the owner's latest saved language. Unowned content returns 404.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "upload", "linkedin", "twitter" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "txt", "srt", "vtt", "json", "md" ], "default": "txt" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact language tag; omitted returns the latest result." } ], "responses": { "200": { "description": "Transcript file body.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Unknown platform or unsupported format.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "402": { "description": "Insufficient credits — a paid plan is required to download.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "Forbidden — API key lacks `transcripts` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Transcript not in the owner's library.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/library/transcripts/{platform}/{externalId}/related": { "get": { "summary": "List related transcripts", "operationId": "listRelatedTranscripts", "tags": [ "library" ], "description": "Related same-channel transcripts saved in the owner's library. Both the source and returned records must belong to the caller.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "upload", "linkedin", "twitter" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Related transcripts.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "related" ], "properties": { "related": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "Unknown platform.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "403": { "description": "Forbidden — API key lacks `transcripts` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/library/transcripts/{platform}/{externalId}": { "get": { "summary": "Get transcript", "operationId": "getTranscript", "tags": [ "library" ], "description": "Retrieve a transcript saved in the authenticated owner's library. Returns 404 if not owned; does not trigger extraction or charge credits.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "upload", "linkedin", "twitter" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Platform-native content id (e.g. dQw4w9WgXcQ for YouTube)." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact language tag to look up. Omitted returns the latest cached result for the asset, regardless of language." } ], "responses": { "200": { "description": "Transcript found.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "transcript" ], "properties": { "transcript": { "$ref": "#/components/schemas/Transcript" }, "cached": { "type": "boolean" } } } } } }, "400": { "description": "Unknown platform.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Transcript not in the owner's library.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } } } } }, "delete": { "summary": "Remove transcript", "operationId": "deleteTranscript", "tags": [ "library" ], "description": "Removes the owner's library/extraction rows for this asset, including a failed-history row that has no transcript body; the global cache is retained. Omit `language` to remove the owner's latest saved or failed language. Owner-scoped: another account's asset is a 404. Removal is permanent — a dismissed failure never reappears.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "upload", "linkedin", "twitter" ] } }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "removed" ], "properties": { "removed": { "type": "boolean" } } } } } }, "400": { "description": "Unknown platform.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "403": { "description": "Forbidden — API key lacks `transcripts` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Transcript not in the owner's library.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/library/batches/{batchId}": { "delete": { "summary": "Remove batch", "operationId": "deleteBatch", "tags": [ "library" ], "description": "Deletes the owner's batch job and its items. Owner-scoped: another account's batch is a 404.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "removed" ], "properties": { "removed": { "type": "boolean" } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "403": { "description": "Forbidden — API key lacks `batches` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Batch not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/youtube/search": { "get": { "summary": "Search", "operationId": "youtubeSearch", "tags": [ "youtube" ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "video", "channel", "playlist" ], "default": "video" } }, { "name": "channelId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "relevance", "date", "rating", "viewCount", "title" ] } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "maxResults", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Search results, cursor-paginated.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "502": { "description": "Discovery unavailable or upstream error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/youtube/videos": { "get": { "summary": "List videos", "operationId": "youtubeVideos", "tags": [ "youtube" ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "videoId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "maxResults", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Video metadata (including caption availability).", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Provide videoId or id.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "502": { "description": "Discovery unavailable or upstream error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/youtube/channels": { "get": { "summary": "Get channels", "operationId": "youtubeChannels", "tags": [ "youtube" ], "description": "Resolve a channel by `id` (UC…) or `handle` (@name or bare).", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "handle", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "maxResults", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Channel metadata.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Provide id or handle.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "502": { "description": "Discovery unavailable or upstream error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/youtube/channels/{channelId}/videos": { "get": { "summary": "List channel videos", "operationId": "youtubeChannelVideos", "tags": [ "youtube" ], "description": "Channel uploads — equivalent to playlistItems on the UU… uploads list.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "maxResults", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Uploaded videos, cursor-paginated.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "404": { "description": "Channel not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "502": { "description": "Discovery unavailable or upstream error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/youtube/playlists/{playlistId}/items": { "get": { "summary": "List playlist items", "operationId": "youtubePlaylistItems", "tags": [ "youtube" ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "playlistId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "maxResults", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Playlist items, cursor-paginated.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "502": { "description": "Discovery unavailable or upstream error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/youtube/captions": { "get": { "summary": "Get captions", "operationId": "youtubeCaptions", "tags": [ "youtube" ], "description": "Returns YouTube caption-track metadata (best-effort; a valid API key can list public-video tracks) alongside the transcript text served by the unified caption service (same permission/quota/proxy path as POST /v1/transcript). A failed or empty Google track query is reported through `trackMetadataStatus`/`trackMetadataError` and never by itself means the video has no captions (`captionAvailable` may be null). This endpoint never creates an ASR job: `requiresAsync: true` is returned when the coordinator confirms speech recognition is required — an `asr`-only request, a confirmed absence of caption tracks, or a confirmed miss of every requested caption language (with `captionAvailable` staying null) — but never from an upstream fault or the wait budget. It requires the `transcripts` scope.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "parameters": [ { "name": "videoId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional caption-language priority list; omitted uses the platform default (`en`). Each entry is tried in order; ASR is not run by this endpoint." } ], "responses": { "200": { "description": "Caption tracks and/or transcript text.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "videoId" ], "properties": { "videoId": { "type": "string" }, "captionAvailable": { "type": "boolean", "nullable": true, "description": "Whether a caption track was found and its text served. `false` only when the extractor confirmed there is no caption track; `null` when unproven (language miss, upstream fault, or metadata that could not be trusted)." }, "tracks": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "trackMetadataStatus": { "type": "string", "enum": [ "complete", "unavailable", "error" ], "description": "How trustworthy the Google track metadata is: complete (listed), unavailable (no client, or the metadata budget elapsed), error (query failed)." }, "trackMetadataError": { "type": "string", "nullable": true }, "trackMetadataErrorCode": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "transcript": { "$ref": "#/components/schemas/Transcript" }, "cached": { "type": "boolean" }, "status": { "type": "string", "enum": [ "success", "unavailable" ] }, "requiresAsync": { "type": "boolean", "description": "True when the coordinator confirms speech recognition is required — an `asr`-only request, a confirmed absence of caption tracks, or a confirmed miss of every requested caption language (with `captionAvailable` staying null). Never inferred from an upstream fault or the wait budget." }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "402": { "description": "Insufficient credits — a paid plan is required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } } }, "403": { "description": "Forbidden — API key lacks `transcripts` scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } } }, "502": { "description": "YouTube discovery is not configured or the upstream failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "503": { "description": "Captions require the transcript service, which is not configured.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } }, "/v1/usage": { "get": { "summary": "Get usage", "operationId": "getUsageV1", "tags": [ "usage" ], "description": "Public, versioned usage/credit summary for the authenticated credential. Free.", "security": [ { "bearer": [] }, { "apiKey": [] } ], "responses": { "200": { "description": "Usage summary.", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } }, "502": { "description": "Usage is not available.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NO_TRANSCRIPT", "IP_BLOCKED", "PO_TOKEN_REQUIRED", "UNAVAILABLE", "CONFIG_ERROR", "LOGIN_REQUIRED", "INVALID_VIDEO", "INSUFFICIENT_CREDITS", "RATE_LIMITED", "UNSUPPORTED_PLATFORM", "NOT_IMPLEMENTED", "CSV_PARSE_ERROR", "ASR_QUOTA_EXCEEDED", "ASR_CONCURRENCY_LIMIT", "TRANSCRIPT_QUOTA_EXCEEDED", "VIDEO_TOO_LONG", "MEDIA_TOO_LARGE", "ASR_REQUIRES_ASYNC", "LANGUAGE_NOT_AVAILABLE", "UPLOAD_INVALID" ] }, "message": { "type": "string" }, "actionLabel": { "type": "string", "description": "Present on 402 errors. Short imperative label for the recovery action (e.g. `Upgrade plan`)." }, "actionUrl": { "type": "string", "description": "Present on 402 errors. Where to send the caller to resolve the gate." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Deprecated alias of `actionUrl`, kept for clients that predate the camelCase hint." }, "availableLanguages": { "type": "array", "items": { "type": "string" }, "description": "Present on 404 when the requested language was not available; the tracks we can serve." } } } } } } } } } } } }, "tags": [ { "name": "transcripts", "description": "Extract, inspect, and retrieve transcripts." }, { "name": "batches", "description": "Process URL lists, playlists, and channels." }, { "name": "library", "description": "Retrieve cached transcripts and manage saved records." }, { "name": "youtube", "description": "Search and enumerate public YouTube resources." }, { "name": "usage", "description": "Inspect the authenticated account's plan and usage." } ] }