> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tornadoapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# n8n Integration

> Use Tornado API in your n8n workflows

## Overview

The official Tornado API node for n8n lets you download YouTube videos and Spotify podcasts directly in your automation workflows.

## Installation

### Via npm (recommended)

```bash theme={null}
cd ~/.n8n/custom
npm install n8n-nodes-tornado-api
```

### Via Docker

```bash theme={null}
docker run -it --rm -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  -v /path/to/n8n-nodes-tornado-api:/home/node/.n8n/custom/n8n-nodes-tornado-api \
  n8nio/n8n
```

### Build from Source

```bash theme={null}
git clone https://github.com/velys-software/n8n-nodes-tornado-api
cd n8n-nodes-tornado-api
npm install
npm run build
```

Then copy to your n8n custom nodes directory.

## Credentials Setup

<Steps>
  <Step title="Open n8n">
    Start n8n and go to **Credentials** in the sidebar
  </Step>

  <Step title="Add New Credential">
    Click **New** and search for **Tornado API**
  </Step>

  <Step title="Enter Details">
    * **API Key**: Your Tornado API key (starts with `sk_`)
    * **Base URL**: `https://api.tornadoapi.io` (default)
  </Step>

  <Step title="Save">
    Click **Save** to store your credentials
  </Step>
</Steps>

## Available Operations

### Job Operations

| Operation               | Description                                     |
| ----------------------- | ----------------------------------------------- |
| **Create**              | Create a download job for a YouTube/Spotify URL |
| **Get Status**          | Check the current status of a job               |
| **Wait for Completion** | Poll until the job completes or fails           |

### Batch Operations

| Operation      | Description                              |
| -------------- | ---------------------------------------- |
| **Get Status** | Check status of a Spotify batch download |

### Storage Operations

| Operation            | Description                         |
| -------------------- | ----------------------------------- |
| **Configure Bucket** | Set up your own S3/R2 bucket        |
| **Reset to Default** | Revert to Tornado's managed storage |

### Account Operations

| Operation     | Description                    |
| ------------- | ------------------------------ |
| **Get Usage** | View your API usage statistics |

## Example Workflows

### Simple YouTube Download

```
Manual Trigger → Tornado API (Create) → Tornado API (Wait) → HTTP Request (Download)
```

1. **Tornado API - Create Job**
   * Resource: Job
   * Operation: Create
   * URL: `https://youtube.com/watch?v=...`

2. **Tornado API - Wait for Completion**
   * Resource: Job
   * Operation: Wait for Completion
   * Job ID: `{{ $json.job_id }}`

3. **HTTP Request**
   * Method: GET
   * URL: `{{ $json.s3_url }}`
   * Response Format: File

### Telegram Bot

```
Telegram Trigger → Tornado API (Create) → Tornado API (Wait) → Telegram (Send Video)
```

1. User sends YouTube URL to bot
2. Tornado downloads the video
3. Bot sends video back to user

### Spotify Podcast Backup

```
Schedule Trigger → Tornado API (Create) → Split In Batches → Tornado API (Wait)
```

1. Runs weekly to backup new episodes
2. Creates batch job for entire show
3. Processes episodes in parallel

## Create Job Options

| Field         | Type   | Description               |
| ------------- | ------ | ------------------------- |
| URL           | string | YouTube or Spotify URL    |
| Format        | select | mp4, mkv, webm, mov       |
| Video Codec   | select | copy, h264, h265, vp9     |
| Audio Codec   | select | copy, aac, opus, mp3      |
| Audio Bitrate | select | 64k to 320k               |
| Video Quality | number | CRF 0-51 (lower = better) |
| Filename      | string | Custom filename           |
| Folder        | string | S3 folder prefix          |
| Webhook URL   | string | Notification URL          |

## S3 Configuration

Configure your own S3-compatible bucket to receive downloads:

1. Add **Tornado API** node
2. Set Resource to **Storage**
3. Set Operation to **Configure Bucket**
4. Fill in your S3 credentials

Supported providers:

* Amazon S3
* Cloudflare R2
* MinIO
* DigitalOcean Spaces
* Any S3-compatible storage

## Error Handling

Use an **IF** node after Wait for Completion:

```
Condition: {{ $json.status }} == "Completed"
```

* **True**: Process the downloaded file
* **False**: Handle the error (send notification, retry, etc.)

## Tips

<CardGroup cols={2}>
  <Card title="Use Webhooks" icon="bell">
    For long downloads, use webhooks instead of polling to avoid timeout issues.
  </Card>

  <Card title="Parallel Processing" icon="bolt">
    Use Split In Batches for Spotify shows to process multiple episodes simultaneously.
  </Card>

  <Card title="Custom Storage" icon="database">
    Configure your own S3 bucket to keep files organized and accessible.
  </Card>

  <Card title="Error Recovery" icon="rotate">
    Add error handling nodes to retry failed downloads automatically.
  </Card>
</CardGroup>

## Support

* [API Documentation](https://docs.tornadoapi.io)
* [GitHub Issues](https://github.com/velys-software/n8n-nodes-tornado-api/issues)
* [Email Support](mailto:support@velys.software)