API Integration Guide

This guide covers how to use Youtarr's API for external integrations, including bookmarklets, mobile shortcuts, and automation tools.

Table of Contents

• Overview
• Authentication
• API Endpoints
• Rate Limiting
• Bookmarklet Setup
• Mobile Shortcuts
• Examples
• Security Considerations
• Troubleshooting

Overview

Youtarr provides an API endpoint that allows you to add YouTube videos to your download queue from external tools. This enables workflows like:

• Browser Bookmarklet: One-click download while browsing YouTube
• Apple Shortcuts: Share videos from the YouTube app on iOS
• Android Tasker/Automate: Automated download workflows
• Home Assistant/n8n: Smart home and automation integrations
• CLI Scripts: Download individual videos

Note: API keys currently support single video downloads only. Playlists, channels, and batch operations are not supported via the API at this time. Use the web UI for those features.

Authentication

API Keys

API keys are the recommended authentication method for external integrations. They provide:

• Persistent access (no expiration)
• Scoped permissions (download endpoint only)
• Easy revocation if compromised
• Rate limiting per key

Creating an API Key

1. Navigate to Settings -> API Keys in Youtarr
2. Click Create Key
3. Enter a descriptive name (e.g., "iPhone Shortcut", "Bookmarklet")
4. Important: Copy and save the key immediately - it will not be shown again!

Using API Keys

Include the API key in the x-api-key header:

curl -X POST https://your-youtarr-server.com/api/videos/download \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'

Session Tokens

You can also use session tokens (the same tokens used by the web UI) via the x-access-token header. However, these expire after 7 days and are less suitable for automation.

API Endpoints

POST /api/videos/download

Add a single YouTube video to the download queue.

Scope Limitation: This endpoint only accepts individual video URLs. Playlist URLs, channel URLs, and batch requests are not supported via API keys. Use the web UI for those operations.

Headers:

Header	Required	Description
Content-Type	Yes	Must be application/json
x-api-key	Yes*	Your API key
x-access-token	Yes*	Session token (alternative to API key)

*One of x-api-key or x-access-token is required.

Request Body:

{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "resolution": "1080",
  "subfolder": "Movies",
  "skipVideoFolder": true
}

Field	Required	Type	Description
url	Yes	string	YouTube video URL
resolution	No	string	Override resolution (360, 480, 720, 1080, 1440, 2160)
subfolder	No	string	Override download subfolder
skipVideoFolder	No	boolean	When true, download files directly into the channel folder without creating a video subfolder

Success Response (200):

{
  "success": true,
  "message": "Video queued for download",
  "video": {
    "title": "Video Title",
    "thumbnail": "https://i.ytimg.com/vi/VIDEO_ID/maxresdefault.jpg",
    "duration": 360
  }
}

Duplicate submissions: URLs are normalized to YouTube video IDs. A video already queued or downloading is not queued again, even when re-downloads are allowed. A successful response includes queued, acceptedIds, and alreadyActiveIds; an already-active single-video request returns HTTP 200 with queued: 0 and an explanatory message. Queue acceptance is confirmed before responding; download execution continues in the background.

Error Responses:

Status	Response	Description
400	{"success": false, "error": "URL is required"}	Missing or invalid URL
401	{"error": "Invalid API key"}	Invalid or missing authentication
403	{"error": "API keys can only access the download endpoint"}	API key used on wrong endpoint
409	{"success": false, "error": "Downloads are paused: ..."}	A storage limit (Settings -> Storage Limits) was reached; the message says which. Retry after storage is back within the limits
429	{"success": false, "error": "Rate limit exceeded"}	Too many requests

API Key Management Endpoints

These endpoints are only accessible via session authentication (not API keys).

GET /api/keys

List all API keys (keys are not shown, only metadata).

POST /api/keys

Create a new API key.

Request Body:

{
  "name": "My Integration"
}

Response:

{
  "success": true,
  "message": "API key created. Save this key - it will not be shown again!",
  "id": 1,
  "name": "My Integration",
  "key": "abc123...",
  "prefix": "abc123"
}

DELETE /api/keys/:id

Delete an API key.

Rate Limiting

API keys are rate-limited to prevent abuse. The default limit is 10 requests per minute per API key.

You can adjust this limit with the Rate Limit (requests/min) field on Settings -> API Keys.

When rate limited, you'll receive a 429 response with:

{
  "success": false,
  "error": "Rate limit exceeded. Try again later."
}

The response includes standard rate limit headers:

• RateLimit-Limit: Maximum requests per window
• RateLimit-Remaining: Remaining requests in current window
• RateLimit-Reset: When the window resets

Bookmarklet Setup

A bookmarklet is a browser bookmark that runs JavaScript when clicked. Youtarr generates a ready-to-use bookmarklet when you create an API key.

Installation

1. Create an API key in Youtarr
2. In the success dialog, drag the "📥 Send to Youtarr" button to your bookmarks bar
3. Alternatively, copy the bookmarklet code and create a bookmark manually

Usage

1. Navigate to any YouTube video page
2. Click the bookmarklet in your bookmarks bar
3. An alert will confirm the video was added to Youtarr

Manual Bookmarklet Code

If you need to create the bookmarklet manually:

javascript:(function(){
  var k='YOUR_API_KEY';
  var s='https://your-youtarr-server.com';
  var u=location.href;
  if(!/youtube\.com|youtu\.be/.test(u)){
    alert('Not YouTube');
    return;
  }
  fetch(s+'/api/videos/download',{
    method:'POST',
    headers:{'Content-Type':'application/json','x-api-key':k},
    body:JSON.stringify({url:u})
  })
  .then(function(r){return r.json()})
  .then(function(d){
    alert(d.success?'✓ Added: '+(d.video&&d.video.title?d.video.title:'Queued'):'✗ '+d.error)
  })
  .catch(function(){alert('✗ Connection failed')})
})();

Replace YOUR_API_KEY and https://your-youtarr-server.com with your values.

Mobile Shortcuts

Apple Shortcuts (iOS/macOS)

1. Create a new Shortcut
2. Add "Get URLs from Input" (for Share Sheet integration)
3. Add "Get Contents of URL" with:
   • URL: https://your-youtarr-server.com/api/videos/download
   • Method: POST
   • Headers: Add x-api-key with your API key
   • Request Body: JSON with {"url": "Shortcut Input"}
4. Add "Show Notification" to confirm success
5. Enable "Show in Share Sheet" and select YouTube

Now you can share videos from the YouTube app directly to Youtarr!

Android (Tasker/Automate)

Create an HTTP Request action with:

• Method: POST
• URL: https://your-youtarr-server.com/api/videos/download
• Headers: Content-Type: application/json, x-api-key: YOUR_KEY
• Body: {"url": "%clipboard"}

Trigger it with a widget or when copying YouTube URLs.

Examples

cURL

# Basic download
curl -X POST https://youtarr.example.com/api/videos/download \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

# With resolution override
curl -X POST https://youtarr.example.com/api/videos/download \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "resolution": "720"}'

Python

import requests

API_KEY = "your_api_key"
SERVER = "https://youtarr.example.com"

def download_video(url, resolution=None):
    payload = {"url": url}
    if resolution:
        payload["resolution"] = resolution
    
    response = requests.post(
        f"{SERVER}/api/videos/download",
        json=payload,
        headers={
            "Content-Type": "application/json",
            "x-api-key": API_KEY
        }
    )
    return response.json()

result = download_video("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(result)

JavaScript (Node.js)

const fetch = require('node-fetch');

const API_KEY = 'your_api_key';
const SERVER = 'https://youtarr.example.com';

async function downloadVideo(url) {
  const response = await fetch(`${SERVER}/api/videos/download`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY
    },
    body: JSON.stringify({ url })
  });
  return response.json();
}

downloadVideo('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
  .then(console.log);

Home Assistant (REST Command)

rest_command:
  youtarr_download:
    url: "https://youtarr.example.com/api/videos/download"
    method: POST
    headers:
      Content-Type: application/json
      x-api-key: "YOUR_API_KEY"
    payload: '{"url": "{{ url }}"}'

Usage in automation:

action:
  - service: rest_command.youtarr_download
    data:
      url: "https://www.youtube.com/watch?v=VIDEO_ID"

Security Considerations

1. Use HTTPS: Always use HTTPS in production to protect your API keys in transit
2. Keep Keys Secret: Never share your API keys or commit them to public repositories
3. Rotate Keys: If a key is compromised, delete it immediately and create a new one
4. Use Descriptive Names: Name your keys by purpose (e.g., "iPhone", "Work Laptop") so you can identify and revoke specific keys if needed
5. Monitor Usage: Check the "Last Used" column to identify unused or suspicious keys
6. External Auth Proxies: If using Cloudflare Zero Trust, Authelia, or similar, you'll need to bypass authentication for /api/videos/download. This is safe because Youtarr's API key authentication still protects the endpoint. See Troubleshooting for setup instructions.

Troubleshooting

"Not YouTube" Alert

The bookmarklet only works on youtube.com or youtu.be pages. Make sure you're on a video page.

"Connection failed" Alert

• Check your Youtarr server is running and accessible
• Verify the server URL in your bookmarklet is correct
• Check browser console for CORS errors

401 Unauthorized

• Verify your API key is correct and active
• Check the key hasn't been deleted

429 Rate Limited

• Wait a minute before trying again
• Consider increasing the rate limit in Settings -> API Keys

CORS Error / Blocked by External Auth (Cloudflare Zero Trust, Authelia, etc.)

If you're running Youtarr behind an authentication proxy like Cloudflare Zero Trust, Authelia, or similar, bookmarklets and external API calls will fail with CORS errors because:

1. The bookmarklet runs from youtube.com (cross-origin)
2. Browser sends a preflight OPTIONS request (no auth headers)
3. Your auth proxy blocks the request before it reaches Youtarr

Solution for Cloudflare Zero Trust:

1. Go to Zero Trust Dashboard → Access → Applications
2. Create a new application for the API endpoint:
   • Application URL: yourdomain.com/api/videos/download
3. Add a policy with:
   • Action: Bypass (not "Allow" - Allow still requires authentication)
   • Selector: Everyone
4. Save the application

The /api/videos/download endpoint is still protected by Youtarr's API key authentication, so this bypass is safe.

Solution for other auth proxies (Authelia, Authentik, etc.):

Configure your proxy to skip authentication for the /api/videos/download path. The exact configuration varies by proxy - consult your proxy's documentation for path-based bypass rules.

Live video status

Authenticated web clients can read GET /api/jobs/video-activity for { instanceId, revision, videos }. Each videos entry is keyed by YouTube ID and contains { jobId, state }, where state is queued or downloading. The videoActivityUpdated WebSocket event signals that clients should refresh this snapshot. Re-fetch on reconnect; a changed instanceId indicates a server restart and resets revision ordering.

POST /api/videos/local-status accepts { "youtubeIds": ["dQw4w9WgXcQ"] } (up to 500 IDs) and returns { results } containing local download status and file metadata. It does not contact YouTube. Use it to refresh search results after downloads finish.