{"openapi":"3.0.3","info":{"title":"Capslane YouTube Transcript API","version":"1.0.0","description":"Retrieve transcripts from public YouTube videos as text or timestamped segments. Read existing captions or follow an asynchronous generation job when captions are unavailable. Authenticate with a workspace API key kept on the server. Transcript submissions reserve a monthly unit; account and job status reads do not. All response examples use synthetic content."},"components":{"securitySchemes":{"capslaneApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Capslane workspace API key. Keep this value on the server."}},"schemas":{}},"paths":{"/v1/account":{"get":{"operationId":"getAccount","summary":"Validate an API key and read its workspace plan","tags":["Transcript"],"description":"Read the workspace plan. Send the workspace key in the x-api-key header. This request reserves no transcript unit.","security":[{"capslaneApiKey":[]}],"responses":{"200":{"description":"The workspace plan for this key. This operation reserves no transcript unit.","content":{"application/json":{"schema":{"description":"The workspace plan for this key. This operation reserves no transcript unit.","type":"object","properties":{"workspace":{"type":"string"},"plan":{"type":"string"},"monthlyLimit":{"minimum":0,"type":"integer"}},"required":["workspace","plan","monthlyLimit"]},"examples":{"account":{"summary":"Workspace plan for the supplied key","value":{"workspace":"Fixture","plan":"free","monthlyLimit":50}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}}}}},"/v1/transcript":{"get":{"operationId":"getYouTubeTranscript","summary":"Retrieve a YouTube transcript or accept a generation job","tags":["Transcript"],"description":"Retrieve a transcript for a public YouTube video. Send x-api-key on every request. url must be an 11-character video ID or a supported HTTPS YouTube URL. Mode accepts native, auto or generate and defaults to auto. Cache lookup precedes mode selection. On a cache miss, native never starts generation; auto starts generation only after confirmed missing captions. A submission reserves a monthly transcript unit before cache lookup. HTTP 200 returns content as timestamped segments by default, or a string only with text=true. source can be native or generated. Read source and cached in the result. Segment offset and duration are milliseconds. lang requests a preferred caption language, not translation. Optional chunkSize accepts 50 to 10000 characters. HTTP 202 returns jobId; save it and poll GET /v1/transcript/{jobId}. This Bash example reads CAPSLANE_API_KEY from the server environment and requests native captions.\n\n```bash\ncurl --fail-with-body --get \"https://capslane.com/v1/transcript\" \\\n  --header \"x-api-key: $CAPSLANE_API_KEY\" \\\n  --data-urlencode \"url=dQw4w9WgXcQ\" \\\n  --data-urlencode \"mode=native\"\n```","parameters":[{"schema":{"minLength":11,"maxLength":2048,"type":"string"},"in":"query","name":"url","required":true},{"schema":{"pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z]{2})?$","maxLength":8,"type":"string"},"in":"query","name":"lang","required":false},{"schema":{"default":false,"type":"boolean"},"in":"query","name":"text","required":false},{"schema":{"minimum":50,"maximum":10000,"type":"integer"},"in":"query","name":"chunkSize","required":false},{"schema":{"anyOf":[{"type":"string","enum":["native"]},{"type":"string","enum":["auto"]},{"type":"string","enum":["generate"]}]},"in":"query","name":"mode","required":false}],"security":[{"capslaneApiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"offset":{"minimum":0,"type":"integer"},"duration":{"minimum":0,"type":"integer"},"lang":{"type":"string"}},"required":["text","offset","duration","lang"]}}]},"lang":{"type":"string"},"availableLangs":{"type":"array","items":{"type":"string"}},"source":{"anyOf":[{"type":"string","enum":["native"]},{"type":"string","enum":["generated"]}]},"cached":{"type":"boolean"},"requestId":{"type":"string"}},"required":["content","lang","availableLangs","source","cached","requestId"]},"examples":{"segments":{"summary":"Cached transcript with timestamps in milliseconds","value":{"content":[{"text":"Synthetic fixture.","offset":1000,"duration":2000,"lang":"en"}],"lang":"en","availableLangs":["en"],"source":"generated","cached":true,"requestId":"req_example"}},"text":{"summary":"Immediate response when text=true","value":{"content":"Synthetic fixture.","lang":"en","availableLangs":["en"],"source":"generated","cached":true,"requestId":"req_example"}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["queued"]},{"type":"string","enum":["downloading"]},{"type":"string","enum":["processing"]},{"type":"string","enum":["persisting"]},{"type":"string","enum":["completed"]},{"type":"string","enum":["failed"]},{"type":"string","enum":["cancelled"]}]},"progress":{"minimum":0,"maximum":100,"type":"integer"},"requestId":{"type":"string"}},"required":["jobId","status","requestId"]},"examples":{"accepted":{"summary":"Generation accepted; save jobId and poll that job","value":{"jobId":"job_550e8400-e29b-41d4-a716-446655440000","status":"queued","requestId":"req_example"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}}}}},"/v1/transcript/{jobId}":{"get":{"operationId":"getTranscriptJob","summary":"Read the status or completed content of an existing job","tags":["Transcript"],"description":"Send x-api-key on every request. Poll the same job ID with a finite deadline. HTTP 200 can report queued, downloading, processing, persisting, completed, failed or cancelled. Stop on failed or cancelled. A completed job with content always returns timestamped segments; source can be native or generated. A completed job without content has no available stored result. Preserve the ID across client timeouts and do not automatically resubmit. Polling reserves no transcript unit. Set CAPSLANE_JOB_ID to the ID returned by the submission.\n\n```bash\ncurl --fail-with-body \"https://capslane.com/v1/transcript/$CAPSLANE_JOB_ID\" \\\n  --header \"x-api-key: $CAPSLANE_API_KEY\"\n```","parameters":[{"schema":{"pattern":"^job_[0-9a-f-]{36}$","type":"string"},"in":"path","name":"jobId","required":true}],"security":[{"capslaneApiKey":[]}],"responses":{"200":{"description":"Job state or completed segments. HTTP 200 does not imply completion. The response examples cover queued, failed, completed and expired results.","content":{"application/json":{"schema":{"description":"Job state or completed segments. HTTP 200 does not imply completion. The response examples cover queued, failed, completed and expired results.","anyOf":[{"description":"A completed job with canonical timestamped segments. The initial text and chunkSize options are not reapplied.","type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["completed"]},"content":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"offset":{"minimum":0,"type":"integer"},"duration":{"minimum":0,"type":"integer"},"lang":{"type":"string"}},"required":["text","offset","duration","lang"]}},"lang":{"type":"string"},"availableLangs":{"type":"array","items":{"type":"string"}},"source":{"anyOf":[{"type":"string","enum":["native"]},{"type":"string","enum":["generated"]}]},"cached":{"type":"boolean","enum":[true]},"requestId":{"type":"string"}},"required":["jobId","status","content","lang","availableLangs","source","cached","requestId"]},{"type":"object","properties":{"jobId":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["queued"]},{"type":"string","enum":["downloading"]},{"type":"string","enum":["processing"]},{"type":"string","enum":["persisting"]},{"type":"string","enum":["completed"]},{"type":"string","enum":["failed"]},{"type":"string","enum":["cancelled"]}]},"progress":{"minimum":0,"maximum":100,"type":"integer"},"requestId":{"type":"string"},"error":{"type":"string"}},"required":["jobId","status","requestId"],"not":{"required":["content"]},"description":"A job status without content. HTTP 200 can include failed or cancelled. A completed job can lack content if its stored result has expired."}]},"examples":{"queued":{"summary":"HTTP 200 while work is still queued","value":{"jobId":"job_550e8400-e29b-41d4-a716-446655440000","status":"queued","requestId":"req_example"}},"failed":{"summary":"HTTP 200 with a failed generation; stop polling","value":{"jobId":"job_550e8400-e29b-41d4-a716-446655440000","status":"failed","progress":50,"error":"upstream_unavailable","requestId":"req_example"}},"completed":{"summary":"Completed job always returns segments, including after text=true","value":{"jobId":"job_550e8400-e29b-41d4-a716-446655440000","status":"completed","content":[{"text":"Synthetic fixture.","offset":1000,"duration":2000,"lang":"en"}],"lang":"en","availableLangs":["en"],"source":"generated","cached":true,"requestId":"req_example"}},"expired":{"summary":"Completed job whose stored content expired; bound polling and report missing content","value":{"jobId":"job_550e8400-e29b-41d4-a716-446655440000","status":"completed","progress":50,"requestId":"req_example"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["error","message","requestId"]}}}}}}}},"servers":[{"url":"https://capslane.com"}],"tags":[{"name":"Transcript","description":"YouTube transcript extraction and generation"}],"externalDocs":{"description":"Authentication, examples, quotas and job polling","url":"https://capslane.com/api-reference"}}