---
name: supadata-ingestion
description: |
  Ingest YouTube transcripts via Supadata.ai API for knowledge extraction.
  Use when you need to extract knowledge from YouTube videos, fetch transcripts,
  or build skills from video content. Supports Claude Code tutorials,
  AI development content, and technical education videos.

allowed-tools:
  - Bash
  - Read
  - Write
---

# Supadata YouTube Ingestion Skill

## Purpose

Fetch YouTube video transcripts using the Supadata.ai API for knowledge extraction and skill building. This skill enables Genesis to learn from video content by extracting transcripts and processing them into structured knowledge.

## API Configuration

- **Endpoint**: `https://api.supadata.ai/v1/transcript`
- **Authentication**: `x-api-key` header with API key from config/secrets.env
- **Rate Limits**: Based on subscription plan (check supadata.ai/pricing)

## Usage

### Fetch a Single Transcript

```bash
python ~/.claude/skills/supadata-ingestion/scripts/fetch_transcript.py \
  --url "https://www.youtube.com/watch?v=VIDEO_ID" \
  --output /path/to/output.json
```

### Batch Fetch Multiple Videos

```bash
python ~/.claude/skills/supadata-ingestion/scripts/fetch_transcript.py \
  --batch videos.txt \
  --output-dir /path/to/transcripts/
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string | Yes* | YouTube video URL or ID |
| batch | string | No | File with list of URLs (one per line) |
| output | string | No | Output file path for single video |
| output-dir | string | No | Directory for batch output |
| lang | string | No | Preferred transcript language (ISO 639-1) |
| mode | string | No | `native` (existing only), `generate` (AI), `auto` (default) |
| text | boolean | No | Return plain text instead of timestamped chunks |

## Response Format

### Timestamped Chunks (default)
```json
{
  "video_id": "abc123",
  "content": [
    {
      "text": "Hello and welcome...",
      "offset": 0,
      "duration": 5000,
      "lang": "en"
    }
  ],
  "lang": "en",
  "availableLangs": ["en", "es"],
  "fetched_at": "2026-02-02T00:00:00Z"
}
```

## Async Processing

For long videos, the API returns a job ID (HTTP 202). The script automatically polls for completion.

## Error Handling

| Code | Meaning | Action |
|------|---------|--------|
| 404 | Video doesn't exist or private | Skip and log |
| 403 | Auth required or restricted | Check API key |
| 206 | Transcript unavailable | Log as unavailable |
| 429 | Rate limited | Wait and retry with exponential backoff |

## Integration with Genesis

Transcripts are stored in the Genesis knowledge pipeline:
- Raw: `data/youtube_knowledge_base/raw/{video_id}.json`
- Processed: `data/youtube_knowledge_base/processed/{video_id}.md`

## References

- [Supadata API Docs](https://docs.supadata.ai/get-transcript)
- See `scripts/fetch_transcript.py` for implementation
