API documentation

Stable v1 endpoints for timestamped single-video summaries and playlist/channel batches.

Authentication

Send an API key using Authorization: Bearer syv_live_…. Keys can be independently scoped and expired. Never place a key in browser code or a public repository.

Create a summary

curl -X POST https://summarizeyoutubevideos.com/api/v1/summaries \
  -H "Authorization: Bearer $SYV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","format":"json"}'

Cached summaries return immediately and consume zero generation credits. Cold summaries normally complete synchronously; use async mode when your HTTP client has a short timeout.

Durable asynchronous jobs

curl -X POST https://summarizeyoutubevideos.com/api/v1/summaries \
  -H "Authorization: Bearer $SYV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"url":"VIDEO_ID","mode":"async","webhookUrl":"https://example.com/webhooks/syv"}'

A 202 response includes a job_… id and Location header. Poll GET /api/v1/jobs/{id}. Polling also resumes a job abandoned by a deployment restart.

Output options

format: json, markdown or text.
language: optional requested output language; language-specific results consume a generation and do not replace the website cache.
includeTranscript: adds timestamped source segments.
webhookUrl: public HTTPS destination, async mode only.

Playlist and channel batches

POST /api/v1/batches
{"url":"https://www.youtube.com/playlist?list=…","limit":30}

GET /api/v1/batches/{id}?format=json

Batches skip Shorts and livestreams, report every skipped count, summarize up to 50 ordinary videos and add a cross-video synthesis.

Errors and retries

Status	Meaning	Retry
400	Invalid request	No
401	Invalid/expired key	No
402	Monthly allowance exhausted	No
403	Missing scope	No
422	Transcript unavailable	No
429	Rate or concurrency limit	After Retry-After
500/502/503	Temporary service failure	Yes, exponential backoff

Every error contains error.code, error.message, error.retryable and requestId.

Safe retries

Send a unique Idempotency-Key (1–128 visible ASCII characters) on summary and batch POST requests. Reusing it with the same body within 24 hours replays the accepted response and sets Idempotency-Replayed: true; using it with different parameters returns 409. Keys are scoped to the API key and endpoint.

Rate limits

The default is 120 requests per minute and 5 concurrent requests per account across all keys. Read X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After. Generation allowance and request throughput are separate controls. Each account may keep up to 10 active keys.

Webhook verification

Each new API key has a separate syv_whsec_… webhook secret, shown once beside the API key and encrypted at rest. Webhooks include X-SYV-Timestamp and X-SYV-Signature: v1=…. Verify HMAC-SHA256 over timestamp.body with that webhook secret and reject old timestamps.

SDK and agent integrations

The repository includes a dependency-free TypeScript SDK under sdk/typescript and a runnable stdio MCP server under integrations/mcp. The MCP server reads SYV_API_KEY from its environment and never accepts secrets in tool calls.

YouTube transcripts and summaries through one stable API