Scority

YouTube API Node.js Guide

Fetch YouTube transcripts from Node.js using the Scority API. Includes fetch examples, API key auth, language options and error handling.

View API docsRead Node examples
Direct answer

Use server-side fetch from Node.js

Node.js integrations can call GET /v1/youtube/transcript directly with fetch. Keep x-api-key on the server and pass video_id, video_url and language through query parameters.

  • Use the production API base URL: https://api.scority.ai.
  • Send exactly one of video_id or video_url.
  • Add language when the workflow needs a specific caption language.
  • Read Retry-After when handling 429 rate_limited responses.
Server-side only

Do not expose x-api-key in browser code

The API key belongs in server-side Node.js code: API routes, workers, background jobs, queue consumers or trusted backend services. Browser code can leak keys through source maps, devtools, logs and network inspection.

  • Use environment variables for SCORITY_API_KEY.
  • Do not put x-api-key in client components or public JavaScript bundles.
  • If a browser app needs transcripts, call your own backend first.

Fetch by video_id

const response = await fetch(
  "https://api.scority.ai/v1/youtube/transcript?video_id=dQw4w9WgXcQ",
  {
    headers: {
      "x-api-key": process.env.SCORITY_API_KEY!,
      "accept": "application/json",
    },
  },
)

const transcript = await response.json()
console.log(transcript.text)

Fetch by video_url and language

const params = new URLSearchParams({
  video_url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  language: "en",
})

const response = await fetch(
  `https://api.scority.ai/v1/youtube/transcript?${params}`,
  {
    headers: { "x-api-key": process.env.SCORITY_API_KEY! },
  },
)

const result = await response.json()
Errors

Handle 401, 429 and 502 deliberately

Node.js integrations should branch on error.code instead of parsing text. Treat input errors, auth errors, quota errors and upstream transcript failures differently.

  • 401 unauthorized: check the x-api-key header and key status.
  • 429 rate_limited: wait for Retry-After before retrying.
  • 429 quota_exceeded: monthly quota is exhausted for the key.
  • 502 upstream_transcript_failed: retry later or inspect the video ID with support.

Preserve normalized error codes

if (!response.ok) {
  const payload = await response.json()
  const code = payload.error?.code

  if (code === "rate_limited") {
    const retryAfter = response.headers.get("Retry-After")
    throw new Error(`Rate limited. Retry after ${retryAfter} seconds.`)
  }

  throw new Error(`Scority API error: ${code}`)
}
SDK status

Use HTTP for production Node.js integrations

The repository contains a private Node client preview for the current transcript endpoint. Public docs should use direct HTTP examples and OpenAPI until package distribution is finalized.

  • Do not add public package-install commands for @scority/sdk until distribution is finalized.
  • Use the OpenAPI spec if you want to generate an internal client.
  • Keep generated clients server-side unless you explicitly proxy requests through your backend.
Reference

API reference

Review the request and response contract for the transcript endpoint.

Open →
Auth

Authentication

Use x-api-key safely from trusted backend code.

Open →
Errors

Error codes

Handle unauthorized, rate_limited and upstream errors by code.

Open →
Guide

YouTube API transcript guide

Clarify official YouTube API intent and transcript API behavior.

Open →