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 (each key reaches one endpoint only)
- Easy revocation if compromised
- Rate limiting per key
There are two kinds of key, chosen when the key is created:
| Key type | Reaches | Use it for |
|---|---|---|
| Download key (default) | POST /api/videos/download | Bookmarklets, phone shortcuts, automation that queues videos |
| Read-only status key | GET /api/status/summary | Dashboards and monitoring tools |
A key of one type is refused on the other endpoint with a 403, so a status key stored in a dashboard can never start a download.
Creating an API Key
- Navigate to Settings -> API Keys & Bookmarklet in Youtarr
- Click Create Key
- Enter a descriptive name (e.g., "iPhone Shortcut", "Bookmarklet")
- For a dashboard or monitoring tool, tick Read-only status key
- 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.
Accepted URLs are watch, Shorts, live, and embed links on youtube.com, m.youtube.com, or music.youtube.com, plus youtu.be links. A watch URL opened from a playlist (watch?v=VIDEO_ID&list=...) downloads only that video; the playlist part is ignored.
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"
}
| 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 |
Any other body fields are ignored. Folder layout (flat or one folder per video) is not selectable per request: it follows the channel's setting, or the global default for untracked channels.
Note: A download requested with a legacy API key is handled like a manual download, so when cookies are enabled it can download members-only videos the cookies' account is a member of. Anyone holding a key can use that membership; keep keys to people you trust with it. See Members-Only Videos.
Success Response (200):
{
"success": true,
"message": "Video queued for download",
"queued": 1,
"acceptedIds": ["VIDEO_ID"],
"alreadyActiveIds": [],
"video": {}
}
Note:
videois currently always an empty object, so clients should not rely on it for the title, thumbnail, or duration. Use the YouTube ID inacceptedIdsinstead.
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 |
| 403 | {"error": "Status API keys can only access the status summary endpoint"} | A read-only status key was used; it cannot start downloads |
| 409 | {"success": false, "error": "Downloads are paused: ..."} | A storage limit (Settings -> Storage Limits) was reached, or the downloads folder looks unavailable (for example a share that is not mounted); the message says which. Retry once that is resolved |
| 429 | {"success": false, "error": "Rate limit exceeded"} | Too many requests |
GET /api/status/summary
A read-only snapshot for dashboards and monitoring tools: library totals, the download queue, the last finished run and the ten most recent downloads, in one request.
Headers:
| Header | Required | Description |
|---|---|---|
x-api-key | Yes* | A read-only status key |
x-access-token | Yes* | Session token (alternative to a status key) |
*One of x-api-key or x-access-token is required. A download key or an External API key is refused with a 403.
curl https://your-youtarr-server.com/api/status/summary \
-H "x-api-key: YOUR_STATUS_KEY_HERE"
Success Response (200):
{
"version": "1.94.0",
"ytDlp": { "version": "2026.11.16" },
"library": { "channels": 42, "videos": 1234, "storageBytes": 123456789012 },
"downloads": {
"paused": false,
"activeJob": { "type": "Channel Downloads", "createdAt": "2026-11-17T20:00:00.000Z" },
"queuedJobs": 2,
"videosDownloading": 1,
"videosQueued": 5
},
"lastRun": {
"status": "success",
"finishedAt": "2026-11-17T19:05:00.000Z",
"lastCheckedAt": "2026-11-17T21:00:00.000Z",
"downloaded": 3,
"failed": 0
},
"recentDownloads": [
{
"youtubeId": "VIDEO_ID",
"title": "Video title",
"channel": "Channel name",
"downloadedAt": "2026-11-17T19:04:00.000Z"
}
]
}
| Field | Description |
|---|---|
version | The running Youtarr version |
ytDlp.version | The installed yt-dlp version, or null before it is known |
library.channels | Subscribed channels |
library.videos | Downloaded videos that are still on disk |
library.storageBytes | Size of those videos, from the file sizes Youtarr recorded (thumbnails, subtitles and other sidecar files are not counted) |
downloads.paused | true while a storage limit, or a downloads folder that looks unavailable, is holding downloads |
downloads.activeJob | The job that is running, or null |
downloads.queuedJobs | Jobs waiting behind it |
downloads.videosDownloading | Videos being downloaded now |
downloads.videosQueued | Videos waiting in the queue that Youtarr already knows by ID (manual and API downloads; a channel check does not know its videos in advance) |
lastRun | The last finished run that downloaded or failed something. status is success, warning or error. lastCheckedAt is later than finishedAt when a newer check found nothing to download. After Youtarr restarts it is rebuilt from the newest finished job in the download history, with finishedAt set to null, until a run finishes. null only when there is no such run at all |
recentDownloads | Up to ten videos, newest first |
Library figures and recentDownloads are cached for up to 30 seconds; the queue and last-run fields are current. The response never contains filesystem paths. Treat fields you do not recognize as additions, not errors.
Error Responses:
| Status | Response | Description |
|---|---|---|
| 401 | {"error": "Invalid API key"} | Unknown or revoked key |
| 403 | {"error": "API keys can only access the download endpoint"} | A download key or an External API key was used |
| 429 | {"error": "Rate limit exceeded. Try again later."} | More than 60 requests in a minute from one status key |
| 500 | {"error": "Failed to build status summary"} | The database could not be read |
Note: With AUTH_ENABLED=false every Youtarr endpoint is open, this one included, so a dashboard that insists on a key can be given any placeholder value.
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"
}
Add "role": "status_read" to create a read-only status key instead of a download key.
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 & Bookmarklet.
That setting covers download keys. A read-only status key has its own fixed limit of 60 requests per minute.
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 windowRateLimit-Remaining: Remaining requests in current windowRateLimit-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
- Create an API key in Youtarr
- In the success dialog, drag the "📥 Send to Youtarr" button to your bookmarks bar
- Alternatively, copy the bookmarklet code and create a bookmark manually
Usage
- Navigate to any YouTube video page
- Click the bookmarklet in your bookmarks bar
- 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)
- Create a new Shortcut
- Add "Get URLs from Input" (for Share Sheet integration)
- Add "Get Contents of URL" with:
- URL:
https://your-youtarr-server.com/api/videos/download - Method: POST
- Headers: Add
x-api-keywith your API key - Request Body: JSON with
{"url": "Shortcut Input"}
- URL:
- Add "Show Notification" to confirm success
- 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
- Use HTTPS: Always use HTTPS in production to protect your API keys in transit
- Keep Keys Secret: Never share your API keys or commit them to public repositories
- Rotate Keys: If a key is compromised, delete it immediately and create a new one
- Use Descriptive Names: Name your keys by purpose (e.g., "iPhone", "Work Laptop") so you can identify and revoke specific keys if needed
- Monitor Usage: Check the "Last Used" column to identify unused or suspicious keys
- External Auth Proxies: If using Cloudflare Zero Trust, Authelia, or similar, you'll need to bypass authentication for
/api/videos/download. This is safe only while Youtarr's own authentication is on: withAUTH_ENABLED=false, Youtarr skips the API key check entirely, and the bypass leaves the endpoint open to anyone who can reach it. 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 & Bookmarklet
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:
- The bookmarklet runs from
youtube.com(cross-origin) - Browser sends a preflight OPTIONS request (no auth headers)
- Your auth proxy blocks the request before it reaches Youtarr
Solution for Cloudflare Zero Trust:
- Go to Zero Trust Dashboard → Access → Applications
- Create a new application for the API endpoint:
- Application URL:
yourdomain.com/api/videos/download
- Application URL:
- Add a policy with:
- Action: Bypass (not "Allow" - Allow still requires authentication)
- Selector: Everyone
- Save the application
The /api/videos/download endpoint is still protected by Youtarr's API key authentication, so this bypass is safe as long as Youtarr's own authentication is enabled.
Warning: If you run Youtarr with
AUTH_ENABLED=falseand rely on the proxy for all authentication (see Authentication), Youtarr accepts every request without checking the API key. Bypassing the proxy for this path then lets anyone who can reach your server queue downloads. Keep Youtarr's authentication on if you add this bypass.
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.
The Sonarr/Radarr bridge needs the same kind of bypass for the /arr/ path, because Sonarr and Radarr can't log in either. See Sonarr and Radarr.
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.