{
  "openapi": "3.1.0",
  "info": {
    "title": "YouTube API — Transcript",
    "version": "1.0.0",
    "description": "Extract video transcripts as timestamped segments and plain text."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/youtube"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error, on every route. Branch on code and retryable rather than on the text; on a 5xx the text is generic. MCP tool errors carry the same fields in structuredContent, and as a JSON text block.",
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in words. For a 400, what to change."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status, repeated in the body."
          },
          "code": {
            "type": "string",
            "description": "The kind of error, stable: invalid_input, unauthorized, insufficient_credits, forbidden, not_found, expired, quota_exceeded, cancelled, time_limit, temporarily_unavailable, posts_unavailable, store_unreachable, upstream_error, internal_error, tool_error. A platform may add its own; more may be added. Treat a code you do not recognise by its retryable flag."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether asking again can succeed."
          },
          "requestId": {
            "type": "string",
            "description": "This request’s id, also sent as the X-Request-Id header. Quote it when reporting a problem."
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "With invalid_input when the request's parameters are refused before the request runs: the parameters that were missing. Always present on those errors, empty when nothing was missing."
          }
        },
        "required": [
          "error",
          "code",
          "retryable",
          "requestId"
        ]
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key."
      }
    }
  },
  "paths": {
    "/transcript": {
      "post": {
        "operationId": "transcript",
        "tags": [
          "Transcript"
        ],
        "summary": "Extract YouTube transcript",
        "description": "Returns the transcript as timestamped segments and joined plain text. Pick the caption language with a language code (default en; en also matches en-US or en-GB). A video with no captions in that language is a 404 naming the languages it has. When YouTube is not answering on every attempt (a bot check or a \"try again later\"), the answer is a retryable 503 temporarily_unavailable; ask again.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "videoUrl": {
                    "type": "string",
                    "description": "YouTube video URL or 11-character video ID. Also accepts youtube.com/live/ and /embed/ links, m.youtube.com and music.youtube.com links, and http://. A URL is echoed unchanged."
                  },
                  "language": {
                    "type": "string",
                    "description": "Transcript language code, such as en or en-US. Optional, defaults to en. A video with no captions in that language is a 404 naming the languages it has.",
                    "example": "en"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "videoUrl"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                    "language": "en"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "segments": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "start": {
                            "type": "number",
                            "description": "Start time in seconds."
                          },
                          "duration": {
                            "type": "number",
                            "description": "Duration in seconds."
                          },
                          "text": {
                            "type": "string",
                            "description": "Transcript text for this segment."
                          }
                        }
                      },
                      "description": "Array of timestamped transcript segments."
                    },
                    "text": {
                      "type": "string",
                      "description": "Full transcript as joined plain text."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "segments": [
                        {
                          "start": 0,
                          "duration": 3.5,
                          "text": "We're no strangers to love"
                        }
                      ],
                      "text": "We're no strangers to love..."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}